[RFC] remote-mips.c: Make sure that each function has an introductory comment
Eli Zaretskii
eliz@gnu.org
Tue Mar 9 17:50:00 GMT 2010
> Date: Mon, 8 Mar 2010 15:18:22 -0700
> From: Kevin Buettner <kevinb@redhat.com>
>
> After Joel noticed that a couple of functions in one of my recent
> patch submissions for remote-mips.c were missing comments, I noticed
> that there were more than a few functions in remote-mips.c that are
> missing introductory comments. Many of the new comments in the patch
> below describe "obvious" functions, but some of them weren't so
> obvious. Since there were a few non-obvious ones, I decided to ask
> for comments prior to committing. So...
Thanks for working on this.
> Comments?
Just a few, from the POV of a more-or-less naive reader:
> +/* Add the checksum specified by *VALUE to the buffer, the last location
> + of which, so far, is specified by *BUF. At the time of this call,
> + the current size of the buffer is RECSIZE.
The usual ambiguity of *size parameters is whether or not it includes
the trailing null character. Many times, the only way to know is to
read the code.
> Return the total size
> + of the buffer after adding the checksum escape, the checksum itself,
> + and the trailing newline.
Again, does this include the null?
> + INAMOUNT is the size of INBUF.
Size of the buffer or length of the text in it?
> + *RECSIZE will be written with the total size of the output buffer
> + prior to returning.
With or without the null?
> +/* Look for the string specified by STRING sent from the target board
> + during a download operation. If the string in question is not seen,
> + output an error message, clean up, and return 0.
What does it mean "clean up" in this case? If it's important to know
about it, perhaps we should tell more; if it's not important, why
mention it?
More information about the Gdb-patches
mailing list