This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [RFC] remote-mips.c: Make sure that each function has an introductory comment
- From: Eli Zaretskii <eliz at gnu dot org>
- To: Kevin Buettner <kevinb at redhat dot com>
- Cc: gdb-patches at sourceware dot org
- Date: Tue, 09 Mar 2010 19:50:05 +0200
- Subject: Re: [RFC] remote-mips.c: Make sure that each function has an introductory comment
- References: <20100308151822.2adfab51@redhat.com>
- Reply-to: Eli Zaretskii <eliz at gnu dot 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?