From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 15078 invoked by alias); 18 Feb 2014 23:38:20 -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 15067 invoked by uid 89); 18 Feb 2014 23:38:19 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-3.2 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_LOW,RP_MATCHES_RCVD,SPF_PASS autolearn=ham version=3.3.2 X-HELO: mail-ve0-f179.google.com Received: from mail-ve0-f179.google.com (HELO mail-ve0-f179.google.com) (209.85.128.179) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES128-SHA encrypted) ESMTPS; Tue, 18 Feb 2014 23:38:18 +0000 Received: by mail-ve0-f179.google.com with SMTP id jx11so14479615veb.10 for ; Tue, 18 Feb 2014 15:38:16 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:in-reply-to:references:date :message-id:subject:from:to:cc:content-type; bh=0IjPDp3I/91B40x5oeovDuxcCL1IxSgg1mOAIml0rKg=; b=io/5+YKY/QPUDx7QDa2ekvF060z4PIAkrckZHTC66Ja06qefSDRU9KEupvAZhjvtAl VzryaONQ2u99/db2d2Id+37IIcj2lwpxDncDH0SLYJUlGVEp9YxN7rwTKNvGWVDqRfw/ GARjPGvdjCaWq4xz+hjaIqR0Yow7o7bX4q+2MtgISfRgdaIjSM2pM3utn6yH4oUpHOrA 1U/1SjXJ4a3hL9VqdVJfzKTc0KknHFzj752Oq5VeBFLvjFD+4oxsjlgUv0HhW0U6Uzc7 c1oficpWdYS8WT8ERmL4bKQgPBo0QPQq8lMvRlzKZJUxDz6xM/Cm5w2PESmF3H6Dw9LG 0tYQ== X-Gm-Message-State: ALoCoQmR5thXxQ00iHaflLYY87aQA+TV8BGsp1WAFNTkTs6YFwbsJyhdSCaoaCv6ixicqn9BEM/N5iBZszD+F1B+vO+gCylzcwjhAT+o3fPAKP9fBzFVsF6nAfTPMvJrNlQ093VecIAYpm8CcCfReE37kkhg8wEeMfOsFsqM29cmkZq7DVMaXzq/I3rGKRg+7XQsnqxBQm1MqkmhY3Qfn8Ooe2r3kGzriA== MIME-Version: 1.0 X-Received: by 10.52.171.68 with SMTP id as4mr19488345vdc.0.1392766695837; Tue, 18 Feb 2014 15:38:15 -0800 (PST) Received: by 10.52.51.234 with HTTP; Tue, 18 Feb 2014 15:38:15 -0800 (PST) In-Reply-To: <5303B9E3.1020406@earthlink.net> References: <530285BC.90102@earthlink.net> <201402172217.s1HMHOAT001833@glazunov.sibelius.xs4all.nl> <5303B9E3.1020406@earthlink.net> Date: Tue, 18 Feb 2014 23:38:00 -0000 Message-ID: Subject: Re: [PATCH] Doxygenate defs.h From: Doug Evans To: Stan Shebs Cc: gdb-patches Content-Type: text/plain; charset=UTF-8 X-IsSubscribed: yes X-SW-Source: 2014-02/txt/msg00581.txt.bz2 On Tue, Feb 18, 2014 at 11:52 AM, Stan Shebs wrote: > On 2/17/14 2:17 PM, Mark Kettenis wrote: >>> 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. > > Really? We have a half-million lines of C, the language whose syntax is > one step above line noise, and it's an extra asterisk in comment blocks > that makes it significantly harder to read? :-) I don't find the new defs.h significantly harder to read at all. I wonder though, having seen it in action so to speak, if "/* * " could be replaced with "/** " (same as now with the space between the * * deleted). >> And what benefit does the >> documentation have over just reading the header file? One thing I like about Doxygen is the improved S/N ratio when trying to understand what the API of any particular module provides. Headers help a bit, but not completely, but it's now worse because when I want to edit a function I now have two files to potentially deal with. Plus I *have* to write a silly little one liner at the function definition site that says "go see the .h". Blech! If I were allowed to disapprove of the move of function documentation to headers I would. > Cross-links and formatting, to start with. For instance, clicking on > the name of a struct in a function signature takes you to its > definition. If reading the header file suffices for you, that's great, > but I personally spend a lot of time grepping around and then trying to > make sense of the spew. > >> 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. > > Doxygen actually has sufficient machinery to build a version of the > internals manual from comment blocks in the code; I didn't lead with > that because the individual construct documentation is useful to > people, and a simpler starting place. But I can start with that if you > like. I like the benefit of an internals manual coming from the code.