From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 18746 invoked by alias); 17 Feb 2014 22:17:33 -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 18735 invoked by uid 89); 17 Feb 2014 22:17:33 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.5 required=5.0 tests=AWL,BAYES_00,RP_MATCHES_RCVD autolearn=ham version=3.3.2 X-HELO: glazunov.sibelius.xs4all.nl Received: from sibelius.xs4all.nl (HELO glazunov.sibelius.xs4all.nl) (83.163.83.176) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-GCM-SHA384 encrypted) ESMTPS; Mon, 17 Feb 2014 22:17:31 +0000 Received: from glazunov.sibelius.xs4all.nl (kettenis@localhost [127.0.0.1]) by glazunov.sibelius.xs4all.nl (8.14.5/8.14.3) with ESMTP id s1HMHPej014275; Mon, 17 Feb 2014 23:17:25 +0100 (CET) Received: (from kettenis@localhost) by glazunov.sibelius.xs4all.nl (8.14.5/8.14.3/Submit) id s1HMHOAT001833; Mon, 17 Feb 2014 23:17:24 +0100 (CET) Date: Mon, 17 Feb 2014 22:17:00 -0000 Message-Id: <201402172217.s1HMHOAT001833@glazunov.sibelius.xs4all.nl> From: Mark Kettenis To: stanshebs@earthlink.net CC: gdb-patches@sourceware.org In-reply-to: <530285BC.90102@earthlink.net> (message from Stan Shebs on Mon, 17 Feb 2014 13:57:16 -0800) Subject: Re: [PATCH] Doxygenate defs.h References: <530285BC.90102@earthlink.net> X-SW-Source: 2014-02/txt/msg00551.txt.bz2 > Date: Mon, 17 Feb 2014 13:57:16 -0800 > From: Stan Shebs > > 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. BTW, you realize this all violates the GNU coding standards. > 2014-02-17 Stan Shebs > > * defs.h: Annotate comments for Doxygen. >