From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 3261 invoked by alias); 22 Dec 2011 20:06:23 -0000 Received: (qmail 3246 invoked by uid 22791); 22 Dec 2011 20:06:20 -0000 X-SWARE-Spam-Status: No, hits=-3.6 required=5.0 tests=AWL,BAYES_00,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,RCVD_IN_DNSWL_NONE,RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from elasmtp-spurfowl.atl.sa.earthlink.net (HELO elasmtp-spurfowl.atl.sa.earthlink.net) (209.86.89.66) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 22 Dec 2011 20:06:06 +0000 Received: from [70.170.59.51] (helo=macbook2.local) by elasmtp-spurfowl.atl.sa.earthlink.net with esmtpa (Exim 4.67) (envelope-from ) id 1Rdoty-0005aM-2O for gdb-patches@sourceware.org; Thu, 22 Dec 2011 15:06:06 -0500 Message-ID: <4EF38DAD.3040106@earthlink.net> Date: Thu, 22 Dec 2011 20:13:00 -0000 From: Stan Shebs User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:8.0) Gecko/20111105 Thunderbird/8.0 MIME-Version: 1.0 To: gdb-patches@sourceware.org Subject: Re: FYI: minsyms documentation References: In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-ELNK-Trace: ae6f8838ff913eba0cc1426638a40ef67e972de0d01da9406b6d93d7fadfdd49fc61fe5da430e0ad350badd9bab72f9c350badd9bab72f9c350badd9bab72f9c 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: 2011-12/txt/msg00794.txt.bz2 On 12/21/11 6:34 PM, Tom Tromey wrote: > I am checking this in on the trunk. > > Today I decided to try to document the minsyms API more or less the way > I would like APIs to be documented in general. This patch implements > that; it move documentation from function definitions to minsyms.h, adds > an introductory comment about minsyms there as well, and it rearranges > the header into a more logical order. I'm not liking this idea very much I'm afraid. First, as you point out later, GDB is not really a library. So internal APIs tend to be pretty fluid, depending on the needs of the moment. But if you mandate that the documentation be in different places depending on function visibility, then the addition or removal of a static keyword must be accompanied by a move of the header comment block. Even if one did nothing more than split an overly-large file (and I note we now have five source files > 10Kloc, long overdue for breakup), then there would have to be massive movement of comment blocks, even if none of the functions actually changed. Plus we already have many functions declared in headers that really are intended to be private, and are only public because of C's limitations; we don't really want to document those as if they are stable API. Second, this is potentially a very large change to the sources, but if it's incremental, then we get into a confusing situation where some files are changed, others are not, and some headers are half-changed because they service multiple source files. I've been digging through the bowels of MI code lately, and am reminded of how many of Andrew's initiatives were never completed, generating all kinds of uncertainty about whether to try to finish them, or roll back, or what. For things that are major stylistic changes, we should at least think about whether we can do some kind of automated transformation that brings all the code into a new consistent state. > My view is that gdbint.texinfo should eventually hold a high-level > overview of the different modules in GDB, but that each individual > module should be documented in the relevant header files. My reason for > this is just that it is simpler to update documentation when it is in > the form of comments. I think gdbint.texinfo should also hold > documentation on our procedures, coding styles, and other things that > are not directly related to some piece of code. Isn't that generally our working assumption now? > In the past people have mentioned using something like Doxygen to > extract an actual document from the sources. I am not opposed to this, > but I think that, as GDB is a program and not a library, such > documentation is of limited value; and in any case there are known > licensing issues with any such scheme -- see the archives of the GCC > lists for details. I agree, Doxygen is not very plausible. It could even be misleading, as Doxygen output tends to make functions look more self-contained and well-defined than would actually be the case for most of GDB. Stan