Re: [RFC] remote-mips.c: Make sure that each function has an introductory comment

[Eli Zaretskii <eliz@gnu.org>]

> 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?