From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 25634 invoked by alias); 9 Aug 2013 09:53:23 -0000 Mailing-List: contact gdb-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-owner@sourceware.org Received: (qmail 25607 invoked by uid 89); 9 Aug 2013 09:53:23 -0000 X-Spam-SWARE-Status: No, score=-2.6 required=5.0 tests=AWL,BAYES_00,KHOP_THREADED,RDNS_NONE autolearn=no version=3.3.1 Received: from Unknown (HELO glazunov.sibelius.xs4all.nl) (83.163.83.176) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Fri, 09 Aug 2013 09:53:22 +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 r799nOVY017550; Fri, 9 Aug 2013 11:49:24 +0200 (CEST) Received: (from kettenis@localhost) by glazunov.sibelius.xs4all.nl (8.14.5/8.14.3/Submit) id r799nMLL024338; Fri, 9 Aug 2013 11:49:23 +0200 (CEST) Date: Fri, 09 Aug 2013 09:53:00 -0000 Message-Id: <201308090949.r799nMLL024338@glazunov.sibelius.xs4all.nl> From: Mark Kettenis To: stanshebs@earthlink.net CC: eliz@gnu.org, dje@google.com, gdb@sourceware.org In-reply-to: <520423A2.6010304@earthlink.net> (message from Stan Shebs on Thu, 08 Aug 2013 16:02:58 -0700) Subject: Re: A new strategy for internals documentation References: <5201781A.3000607@earthlink.net> <83k3jyunt8.fsf@gnu.org> <5202A6D6.8090908@earthlink.net> <83li4ct7ot.fsf@gnu.org> <8361vfu9t4.fsf@gnu.org> <520423A2.6010304@earthlink.net> X-SW-Source: 2013-08/txt/msg00043.txt.bz2 > Date: Thu, 08 Aug 2013 16:02:58 -0700 > From: Stan Shebs > > 3. Introduce an annotation/structured scheme in source code comments. > > You're skeptical, but not opposed to this, right? It's not going to make the source code comments more readable. Will probably make people focus on getting the sybtax of the annotations right instead of the actual context. > 4. Use Doxygen. > > Are you for or against, or indifferent? > > (For me Doxygen gets the nod by elimination, if nothing else. In the > rather lengthy > > http://en.wikipedia.org/wiki/Comparison_of_documentation_generators > > there are not a lot of options that are portable, GPL, etc. LLVM's use > of Doxygen, http://llvm.org/doxygen/index.html , seems pretty useful.) Yeah, that's a typical example of doxygen-generated documentation. Lots of function prototypes, a few inheritance diagrams, and barely any actual content. Not my defenition of useful. In fact I'm pretty much conditioned such that my response to seeing doxygen generated pages is to not ever bother reading it. Stan, I fear you're proposing a technical solution for a social probleem.