From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 16677 invoked by alias); 9 Aug 2013 09:13:01 -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 16646 invoked by uid 89); 9 Aug 2013 09:13:00 -0000 X-Spam-SWARE-Status: No, score=-3.7 required=5.0 tests=AWL,BAYES_00,KHOP_THREADED,RCVD_IN_DNSWL_NONE,RCVD_IN_HOSTKARMA_NO,RDNS_NONE,SPF_SOFTFAIL autolearn=no version=3.3.1 Received: from Unknown (HELO mtaout20.012.net.il) (80.179.55.166) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Fri, 09 Aug 2013 09:12:59 +0000 Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0MR900J00AOCOY00@a-mtaout20.012.net.il> for gdb@sourceware.org; Fri, 09 Aug 2013 12:12:20 +0300 (IDT) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0MR900J4GAWKBQA0@a-mtaout20.012.net.il>; Fri, 09 Aug 2013 12:12:20 +0300 (IDT) Date: Fri, 09 Aug 2013 09:13:00 -0000 From: Eli Zaretskii Subject: Re: A new strategy for internals documentation In-reply-to: To: Doug Evans Cc: stanshebs@earthlink.net, gdb@sourceware.org Reply-to: Eli Zaretskii Message-id: <83vc3frzwa.fsf@gnu.org> References: <5201781A.3000607@earthlink.net> <83k3jyunt8.fsf@gnu.org> <5202A6D6.8090908@earthlink.net> <83li4ct7ot.fsf@gnu.org> <8361vfu9t4.fsf@gnu.org> X-SW-Source: 2013-08/txt/msg00039.txt.bz2 > Date: Thu, 8 Aug 2013 16:04:49 -0700 > From: Doug Evans > Cc: Stan Shebs , gdb > > On Thu, Aug 8, 2013 at 2:55 PM, Eli Zaretskii wrote: > >> Date: Thu, 8 Aug 2013 14:07:51 -0700 > >> From: Doug Evans > >> Cc: Stan Shebs , gdb > > [...] > >> > The grumbles come from people other than those who can provide the > >> > documentation. And the latter don't think we have a problem in the > >> > first place. > >> > >> If the latter includes me I disagree. > > > > Disagree with what, and why? > > I disagree with the statement "the latter don't think we have a problem". > We do have a problem: I think our internals documentation needs improving. Then you seem to belong to the same minority as I do. > >> > Why do you need development for comments? > >> > >> He's referring to development of the comment->doc generator. > > > > Why do we need that developed, if it already does the job? > > Assuming it doesn't have latent bugs that no one has tripped over yet, > and assuming it does everything we want, now and tomorrow. What is good enough for libiberty and binutils ought to be good enough for us. > I'm one that thinks that there is not enough, and that expanding the > comments is not enough. For one there's a higher level / descriptive > view that's missing with that approach. Plus the S/N ratio when faced > with reading all the source code is much lower than when able to > browse something generated from the comments in the code. I think the same, but others don't, as was demonstrated numerous times in past discussions.