From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 30210 invoked by alias); 19 Feb 2014 01:47:26 -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 30199 invoked by uid 89); 19 Feb 2014 01:47:25 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.6 required=5.0 tests=AWL,BAYES_00 autolearn=ham version=3.3.2 X-HELO: relay1.mentorg.com Received: from relay1.mentorg.com (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Wed, 19 Feb 2014 01:47:23 +0000 Received: from svr-orw-fem-01.mgc.mentorg.com ([147.34.98.93]) by relay1.mentorg.com with esmtp id 1WFwFq-0006i8-04 from Yao_Qi@mentor.com ; Tue, 18 Feb 2014 17:47:18 -0800 Received: from SVR-ORW-FEM-05.mgc.mentorg.com ([147.34.97.43]) by svr-orw-fem-01.mgc.mentorg.com over TLS secured channel with Microsoft SMTPSVC(6.0.3790.4675); Tue, 18 Feb 2014 17:47:17 -0800 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; Tue, 18 Feb 2014 17:46:38 -0800 Message-ID: <53040CB3.4020001@codesourcery.com> Date: Wed, 19 Feb 2014 01:47: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: "Jose E. Marchesi" CC: Mark Kettenis , , Subject: Re: [PATCH] Doxygenate defs.h References: <530285BC.90102@earthlink.net> <201402172217.s1HMHOAT001833@glazunov.sibelius.xs4all.nl> <8738jg4pj1.fsf@oracle.com> In-Reply-To: <8738jg4pj1.fsf@oracle.com> Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 8bit X-IsSubscribed: yes X-SW-Source: 2014-02/txt/msg00585.txt.bz2 On 02/18/2014 07:40 PM, Jose E. Marchesi wrote: > Most developers will just open the header files and read them, using > some indexing tool (ctags, CEDET/Emacs, whatever Eclipse uses..) for > jumping through references. IMO polluting the comments like this, > restating the obvious with marks like @param, will only make them more > difficult to read with no practical benefit: what gdb hacker will ever > fire up a Firefox or similar to find out what the parameters to some > function are? I feel @param is useful here. "@param arg" is equivalent to "ARG" we are using in comments nowadays, but more descriptive, IMO. It should not confuse any GDB newbie. Some refactor tools can update @param when argument is renamed, to keep comments consistent with code. We use doxygen to generate internal documentation from source code, not only function comments, but also general overview of each 'module'. It isn't hard to understand each function comments but hard to get a big picture of each 'module'. Doxygen helps! -- Yao (齐尧)