From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 18889 invoked by alias); 18 Feb 2014 11:37:51 -0000 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 Received: (qmail 18879 invoked by uid 89); 18 Feb 2014 11:37:51 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.0 required=5.0 tests=AWL,BAYES_00,RP_MATCHES_RCVD,SPF_PASS,UNPARSEABLE_RELAY autolearn=ham version=3.3.2 X-HELO: aserp1040.oracle.com Received: from aserp1040.oracle.com (HELO aserp1040.oracle.com) (141.146.126.69) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-SHA encrypted) ESMTPS; Tue, 18 Feb 2014 11:37:50 +0000 Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id s1IBbkSK025078 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 18 Feb 2014 11:37:46 GMT Received: from userz7021.oracle.com (userz7021.oracle.com [156.151.31.85]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s1IBbi7x008730 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Tue, 18 Feb 2014 11:37:45 GMT Received: from abhmp0020.oracle.com (abhmp0020.oracle.com [141.146.116.26]) by userz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s1IBbixF002684; Tue, 18 Feb 2014 11:37:44 GMT Received: from termi.oracle.com (/10.175.48.20) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 18 Feb 2014 03:37:44 -0800 From: jose.marchesi@oracle.com (Jose E. Marchesi) To: Mark Kettenis Cc: stanshebs@earthlink.net, gdb-patches@sourceware.org Subject: Re: [PATCH] Doxygenate defs.h References: <530285BC.90102@earthlink.net> <201402172217.s1HMHOAT001833@glazunov.sibelius.xs4all.nl> Date: Tue, 18 Feb 2014 11:37:00 -0000 In-Reply-To: <201402172217.s1HMHOAT001833@glazunov.sibelius.xs4all.nl> (Mark Kettenis's message of "Mon, 17 Feb 2014 23:17:24 +0100 (CET)") Message-ID: <8738jg4pj1.fsf@oracle.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-IsSubscribed: yes X-SW-Source: 2014-02/txt/msg00562.txt.bz2 > This is a first patch that modifies source code to be more useful with > Doxygen. It does little more than add an extra "*" to comment blocks > that document the source construct immediately following. > > In keeping with our usual practice, I have not changed anything outside > comments, and the comments themselves are only minimally tweaked, > despite the great temptation to expand on some of the more cryptic. :-) > > I'll push this in a couple days if people are willing to live with this > format for comments. Next up, minsyms.h. Sorry, no, I'm not willing to live with this. It's making the comments significantly harder to read. And what benefit does the documentation have over just reading the header file? There really is only one thing that the old internals documentation tried to provide that the comments in the source code aren't very good at: explaining how the interfaces work together. And that's not something Doxygen is going to provide. I am of the same opinion. Usually only managers ever "use" Doxygen-generated "documentation" of C programs, and mostly only because it is required as a deliverable by contractual reasons. Most developers will just open the header files and read them, using some indexing tool (ctags, CEDET/Emacs, whatever Eclipse uses..) for jumping through references. IMO polluting the comments like this, restating the obvious with marks like @param, will only make them more difficult to read with no practical benefit: what gdb hacker will ever fire up a Firefox or similar to find out what the parameters to some function are? If the decision to use Doxygen has been already taken, would it be possible to at least avoid these @param marks?