From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 30292 invoked by alias); 21 Dec 2007 16:30:56 -0000 Received: (qmail 30283 invoked by uid 22791); 21 Dec 2007 16:30:55 -0000 X-Spam-Check-By: sourceware.org Received: from romy.inter.net.il (HELO romy.inter.net.il) (213.8.233.24) by sourceware.org (qpsmtpd/0.31) with ESMTP; Fri, 21 Dec 2007 16:30:45 +0000 Received: from HOME-C4E4A596F7 (IGLD-84-229-233-247.inter.net.il [84.229.233.247]) by romy.inter.net.il (MOS 3.7.3-GA) with ESMTP id JRI56305 (AUTH halo1); Fri, 21 Dec 2007 18:30:23 +0200 (IST) Date: Fri, 21 Dec 2007 16:34:00 -0000 Message-Id: From: Eli Zaretskii To: Joel Brobecker CC: uweigand@de.ibm.com, gdb-patches@sourceware.org In-reply-to: <20071221043608.GJ6154@adacore.com> (message from Joel Brobecker on Fri, 21 Dec 2007 08:36:08 +0400) Subject: Re: [RFC/RFA] Introduce new struct parse_context Reply-to: Eli Zaretskii References: <20071217064213.GC9022@adacore.com> <20071221043608.GJ6154@adacore.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: 2007-12/txt/msg00379.txt.bz2 > Date: Fri, 21 Dec 2007 08:36:08 +0400 > From: Joel Brobecker > Cc: uweigand@de.ibm.com, gdb-patches@sourceware.org > > I would tend to say that your suggestion is a good one, and we should > request documentation when necessary. But I think that this should > be evaluated on a case-by-case basis, because there are some times > when external documents such as gdbint will be more useful, and other > times when it will be more appropriate to leave the documentation > as a comment embedded in the code. > > Let's take the two patches of this thread as an example. Would you > suggest to move the documentation to gdbint, or leave it in the > code? To me, it seems better to put keep the documentation with > the code. We had this discussion in the past, and I'm well aware that some of the maintainers think that code comments are better than a manual that documents the internals. I can only reiterate what I wrote back then: I think code comments are not a replacement for a good internals manual. Comments don't have a structure. They lack good cross-referencing facilities. They don't have any efficient ways of searching for text by a word or phrase that describes the topic or subject we are looking for (something like index search in Info). Comments also tend to describe details, but not the overall picture. In sum, I think comments are not appropriate for someone who wants to learn about a subject she knows next to nothing about. > If we were to put some documentation in gdbint for this patch, > what would you put? Both. This is a significant new feature, and at least its main principles should be described in gdbint, enough to get the reader off the ground with the knowledge she could use to find the parts of code which implement this feature (and read the comments there ;-).