From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 15039 invoked by alias); 9 Mar 2010 17:50:14 -0000 Received: (qmail 15030 invoked by uid 22791); 9 Mar 2010 17:50:13 -0000 X-SWARE-Spam-Status: No, hits=-0.8 required=5.0 tests=AWL,BAYES_00,RCVD_IN_SORBS_WEB,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mtaout22.012.net.il (HELO mtaout22.012.net.il) (80.179.55.172) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Tue, 09 Mar 2010 17:50:07 +0000 Received: from conversion-daemon.a-mtaout22.012.net.il by a-mtaout22.012.net.il (HyperSendmail v2007.08) id <0KZ100400039HW00@a-mtaout22.012.net.il> for gdb-patches@sourceware.org; Tue, 09 Mar 2010 19:50:05 +0200 (IST) Received: from HOME-C4E4A596F7 ([77.126.34.234]) by a-mtaout22.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0KZ100M2407FVBJ0@a-mtaout22.012.net.il>; Tue, 09 Mar 2010 19:50:04 +0200 (IST) Date: Tue, 09 Mar 2010 17:50:00 -0000 From: Eli Zaretskii Subject: Re: [RFC] remote-mips.c: Make sure that each function has an introductory comment In-reply-to: <20100308151822.2adfab51@redhat.com> To: Kevin Buettner Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <83lje12xma.fsf@gnu.org> References: <20100308151822.2adfab51@redhat.com> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2010-03/txt/msg00357.txt.bz2 > Date: Mon, 8 Mar 2010 15:18:22 -0700 > From: Kevin Buettner > > 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?