From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 26235 invoked by alias); 10 Aug 2013 01:13:06 -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 26209 invoked by uid 89); 10 Aug 2013 01:13:05 -0000 X-Spam-SWARE-Status: No, score=-4.2 required=5.0 tests=AWL,BAYES_00,KHOP_RCVD_UNTRUST,KHOP_THREADED,RCVD_IN_HOSTKARMA_W,RCVD_IN_HOSTKARMA_WL,RDNS_NONE autolearn=no version=3.3.1 Received: from Unknown (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Sat, 10 Aug 2013 01:13:04 +0000 Received: from svr-orw-exc-10.mgc.mentorg.com ([147.34.98.58]) by relay1.mentorg.com with esmtp id 1V7xjk-0003zD-KV from Yao_Qi@mentor.com ; Fri, 09 Aug 2013 18:12:56 -0700 Received: from SVR-ORW-FEM-05.mgc.mentorg.com ([147.34.97.43]) by SVR-ORW-EXC-10.mgc.mentorg.com with Microsoft SMTPSVC(6.0.3790.4675); Fri, 9 Aug 2013 18:12:56 -0700 Received: from qiyao.dyndns.org (147.34.91.1) by svr-orw-fem-05.mgc.mentorg.com (147.34.97.43) with Microsoft SMTP Server id 14.2.247.3; Fri, 9 Aug 2013 18:12:55 -0700 Message-ID: <52059367.3040300@codesourcery.com> Date: Sat, 10 Aug 2013 01:13:00 -0000 From: Yao Qi User-Agent: Mozilla/5.0 (X11; Linux i686; rv:17.0) Gecko/20130110 Thunderbird/17.0.2 MIME-Version: 1.0 To: Doug Evans CC: Eli Zaretskii , Stan Shebs , gdb 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> In-Reply-To: Content-Type: text/plain; charset="UTF-8"; format=flowed Content-Transfer-Encoding: 8bit X-SW-Source: 2013-08/txt/msg00060.txt.bz2 On 08/09/2013 07:04 AM, Doug Evans wrote: > 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. Code comments can be about high-level view too. Existing comments in the beginning of event-loop.h and remote-notif.c are about high-level view. Document is generated from the comments, and we need some special annotations or markups to identify these comments are descriptive views for a certain module or components. Doxygen or other documentation generators are able to do that. -- Yao (齐尧)