From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 17134 invoked by alias); 16 Oct 2013 17:28:25 -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 17116 invoked by uid 89); 16 Oct 2013 17:28:23 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-3.7 required=5.0 tests=AWL,BAYES_00,RP_MATCHES_RCVD,SPF_HELO_PASS,SPF_PASS autolearn=ham version=3.3.2 X-HELO: mx1.redhat.com Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Wed, 16 Oct 2013 17:28:22 +0000 Received: from int-mx02.intmail.prod.int.phx2.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id r9GHSIBf027715 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 16 Oct 2013 13:28:18 -0400 Received: from barimba (ovpn-113-54.phx2.redhat.com [10.3.113.54]) by int-mx02.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id r9GHSHwn026223 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES128-SHA bits=128 verify=NO); Wed, 16 Oct 2013 13:28:17 -0400 From: Tom Tromey To: Stan Shebs Cc: gdb-patches@sourceware.org Subject: Re: [RFC] Use Doxygen for internals documentation References: <525877F6.40001@earthlink.net> Date: Wed, 16 Oct 2013 17:28:00 -0000 In-Reply-To: <525877F6.40001@earthlink.net> (Stan Shebs's message of "Fri, 11 Oct 2013 15:13:10 -0700") Message-ID: <87bo2pw2fj.fsf@fleche.redhat.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-SW-Source: 2013-10/txt/msg00492.txt.bz2 >>>>> "Stan" == Stan Shebs writes: Stan> This patch is the third and final step in the transition away from the Stan> old GDB internals manual. Thanks, Stan. I applied your patch and built the docs locally. This went smoothly. I don't have a problem with the new way of formatting comments, or with requiring them in review. It seems to me that we should require docs for extern objects. For static objects I think it's fine to use less formal comments; but I'm curious what others think. Looking at the generated docs makes me wonder what knobs we have to change the output. Here's what I noticed: I started by looking at the minsyms section. I rearranged minsyms a while back to have the comments in the header and to try to make it act somewhat more like a self-contained module. So, I was particularly curious how this would render. Starting here it looks promising enough: http://stanshebs.github.io/gdb-doxy-test/gdb-api/pages.html (When we have two dozen modules here will we be able to organize them somehow?) Clicking through to the Minimal Symbols page, though, just gives some text about the header. (As an aside it's clear that this paragraph needs a rewrite for Doxygen...) However, there's nothing there about the module API, nor any link to minsyms.h. Is the latter something we can add? I can go to the files page: http://stanshebs.github.io/gdb-doxy-test/gdb-api/files.html and click through to minsyms.h: http://stanshebs.github.io/gdb-doxy-test/gdb-api/minsyms_8h.html This lays out the contents of the file -- but not any introductory text. So that seems odd. And, the contents are in an arbitrary order: Classes, Defines, Functions. What if we arranged the file in a particular order to emphasize related things? Could we reflect this in the docs somehow? Finally, having to go to the Files page is sub-optimal just because it presumes that one knows the layout. It would be better if we could start from some top-level view of "Modules of GDB" and click through to the modules to understand their details. I think it's fine to move forward even if all the answers are negative. It's definitely an improvement. Tom