From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 22778 invoked by alias); 14 Oct 2013 13:20: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 22764 invoked by uid 89); 14 Oct 2013 13:20:24 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=1.2 required=5.0 tests=AWL,BAYES_00,GARBLED_BODY autolearn=no version=3.3.2 X-HELO: relay1.mentorg.com Received: from relay1.mentorg.com (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Mon, 14 Oct 2013 13:20:24 +0000 Received: from svr-orw-exc-10.mgc.mentorg.com ([147.34.98.58]) by relay1.mentorg.com with esmtp id 1VVi4K-0004J9-BD from Yao_Qi@mentor.com ; Mon, 14 Oct 2013 06:20:20 -0700 Received: from SVR-ORW-FEM-02.mgc.mentorg.com ([147.34.96.206]) by SVR-ORW-EXC-10.mgc.mentorg.com with Microsoft SMTPSVC(6.0.3790.4675); Mon, 14 Oct 2013 06:20:20 -0700 Received: from qiyao.dyndns.org (147.34.91.1) by svr-orw-fem-02.mgc.mentorg.com (147.34.96.168) with Microsoft SMTP Server id 14.2.247.3; Mon, 14 Oct 2013 06:20:19 -0700 Message-ID: <525BEF41.6010807@codesourcery.com> Date: Mon, 14 Oct 2013 13:20:00 -0000 From: Yao Qi User-Agent: Mozilla/5.0 (X11; Linux i686; rv:17.0) Gecko/20130110 Thunderbird/17.0.2 MIME-Version: 1.0 To: Stan Shebs CC: Subject: Re: [RFC] Use Doxygen for internals documentation References: <525877F6.40001@earthlink.net> In-Reply-To: <525877F6.40001@earthlink.net> Content-Type: text/plain; charset="UTF-8"; format=flowed Content-Transfer-Encoding: 8bit X-IsSubscribed: yes X-SW-Source: 2013-10/txt/msg00433.txt.bz2 On 10/12/2013 06:13 AM, Stan Shebs wrote: > This patch is the third and final step in the transition away from the > old GDB internals manual. > I tried this patch, and overall, I like the doc generated by doxygen. > > To try it out, install doxygen, apply this patch to GDB, configure in > the usual way, then do > > make doxy > > in the doc objdir. This will produce a "doxy" subdir, with three > subdirs in turn, each based on a different config file: > > doxy/gdb-api - GDB's "API", basically what is in .h files > doxy/gdb-xref - the full xref, voluminous Any reason to produce both of them? I'd like to have a single one. > doxy/gdbserver - GDBserver xref > doxy/xml - XML version, for further script-crunching Do you have an example that these xml files can be consumed by other tools? > > To see how the annotations work, look down through minsyms.h and > utils.h, you can see the comments attached to declarations. > > types, see what is used and what is not used. > > So I think it's worth going ahead and introducing. But of course > something like this only works if everybody signs on, patches are > required to have Doxygen annotations for header file additions, and > so forth. Look at the header file changes, try noodling around the > Doxygen output, see if you're willing to be looking at all this for > the next N years. > With this change, we need to write comments in a new way for doxygen. I go through your patch to minsyms.h, and think the comment style looks fine to me. -- Yao (齐尧)