From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 32315 invoked by alias); 8 Aug 2013 23:04:58 -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 32297 invoked by uid 89); 8 Aug 2013 23:04:57 -0000 X-Spam-SWARE-Status: No, score=-3.5 required=5.0 tests=AWL,BAYES_00,KHOP_THREADED,RCVD_IN_DNSWL_LOW,RCVD_IN_HOSTKARMA_YE,RDNS_NONE,SPF_PASS autolearn=ham version=3.3.1 Received: from Unknown (HELO mail-ie0-f179.google.com) (209.85.223.179) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Thu, 08 Aug 2013 23:04:57 +0000 Received: by mail-ie0-f179.google.com with SMTP id c11so2878532ieb.24 for ; Thu, 08 Aug 2013 16:04:49 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=x-gm-message-state:mime-version:in-reply-to:references:date :message-id:subject:from:to:cc:content-type; bh=kVAUbIznPXAS3DypiCkcv3iEFjqjmkFVyVYu8wZbOZE=; b=YXsUu/vXLvR59e7BtwwiSf6OoKKkBL5oxzJ4NVyEeFBQkCqM185kz6p0iRoy1RLayL J3gCQQdT4R9bkfTDyYwHR4UgYHnFAU7QlqAAUPHyUSicISaattTmJ/0FxJ3Akcj5qN/t PdnVDPJG43mFG9UMWRtkNcMhzPHwPVJpsM1Cs5qCfAv1Pe8TkTLF2BOa3vDgfcULR9dI nAymqF2HU6gcZJHnsLx0HaECJsHTAQdi+xt4xhsgNcBt/eLdZ8tm9RY1vPdO44FdIcv4 5qHHHVKNwtjKsv5/r/3/9jKVDDR1QBxJlwJdarC1kHYPuHPEVeSAmx5tV1aHQuHinXLj St2w== X-Gm-Message-State: ALoCoQmqAQjranN4KznbGHM4a/FgbA3uN1WQUFwybU/086sE221BHwX4lWditsPNGHQQv5B3IQ51kdQhr2nfxNKvgHqJ6mTeSjtdGGkCSIrwolcS6REdyx+StnQg9xouyyRsdLO69khx/wahZuFr6VN70b1veLoVRlDys01FWvpsBRI+V6MYjXj5+MsNxsQpUCZtQl4qVmJa MIME-Version: 1.0 X-Received: by 10.50.7.101 with SMTP id i5mr668256iga.48.1376003089733; Thu, 08 Aug 2013 16:04:49 -0700 (PDT) Received: by 10.64.239.148 with HTTP; Thu, 8 Aug 2013 16:04:49 -0700 (PDT) In-Reply-To: <8361vfu9t4.fsf@gnu.org> References: <5201781A.3000607@earthlink.net> <83k3jyunt8.fsf@gnu.org> <5202A6D6.8090908@earthlink.net> <83li4ct7ot.fsf@gnu.org> <8361vfu9t4.fsf@gnu.org> Date: Thu, 08 Aug 2013 23:04:00 -0000 Message-ID: Subject: Re: A new strategy for internals documentation From: Doug Evans To: Eli Zaretskii Cc: Stan Shebs , gdb Content-Type: text/plain; charset=ISO-8859-1 X-SW-Source: 2013-08/txt/msg00034.txt.bz2 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. >> > Again, if we don't care about the documentation, then of course we >> > shouldn't care about poor information. If we do care, then wiki is a >> > way to waste resources at best. >> >> I disagree (that the wiki is a way to waste resources at best). > > It is a waste because nothing good will ever come out of it. It will > be a heap of notes various people at various times thought it would be > a good idea to share. You cannot create a coherent document that way. I think we'll have to agree to disagree that nothing good will come out of it. For example, gdb's current wiki pages are useful, and are edited far more often than gdbint.texinfo (AFAICT). >> > 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. >> > The net result will be that the documentation will be unreadable. Not >> > everybody who writes good code can write good documentation. >> >> OTOH, It's easier to improve documentation over time. > > Who will do that, and why? Again, the core developers think that what > we have in the comments is enough, and if it is not enough, the > comments should be improved/expanded. Why would someone invest > efforts in another resource? 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.