From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 13419 invoked by alias); 17 Mar 2014 17:15:00 -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 13407 invoked by uid 89); 17 Mar 2014 17:15:00 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-3.7 required=5.0 tests=AWL,BAYES_00,SPF_HELO_PASS,SPF_PASS,T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 X-HELO: mx1.redhat.com Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Mon, 17 Mar 2014 17:14:58 +0000 Received: from int-mx12.intmail.prod.int.phx2.redhat.com (int-mx12.intmail.prod.int.phx2.redhat.com [10.5.11.25]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id s2HHEtHc030039 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Mon, 17 Mar 2014 13:14:56 -0400 Received: from greed.delorie.com (ovpn-113-26.phx2.redhat.com [10.3.113.26]) by int-mx12.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id s2HHEs1s030684 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Mon, 17 Mar 2014 13:14:55 -0400 Received: from greed.delorie.com (greed.delorie.com [127.0.0.1]) by greed.delorie.com (8.14.4/8.14.4) with ESMTP id s2HHEse5028784 for ; Mon, 17 Mar 2014 13:14:54 -0400 Received: (from dj@localhost) by greed.delorie.com (8.14.4/8.14.4/Submit) id s2HHErgl028783; Mon, 17 Mar 2014 13:14:53 -0400 From: DJ Delorie To: gdb-patches@sourceware.org Subject: Re: [RFC] Stop putting function comments in foo.h References: <53271DC0.3050405@redhat.com> Date: Mon, 17 Mar 2014 17:15:00 -0000 In-Reply-To: <53271DC0.3050405@redhat.com> (Pedro Alves's message of "Mon, 17 Mar 2014 16:07:28 +0000") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-IsSubscribed: yes X-SW-Source: 2014-03/txt/msg00392.txt.bz2 Pedro Alves writes: > Whenever I look at a header file that doesn't document its > functions' interfaces (and often doesn't even list the > parameter names), I get depressed and disappointed. I'm > wondering if it's just me. :-) Speaking from the "someone who uses the API but doesn't understand the source tree" point of view, it's usually a lot easier to discover an API through the header files, and that's where I expect to find some documentation about the API. The only time that documentation-in-source works is when there's a strict one-to-one mapping of headers to sources, else finding the documentation becomes yet another task to hurdle. Also, I've yet to find a doxygen doc set that adds any value over just commenting the headers. Also, IMHO there should be *two* sets of in-source docs: the headers should have comments suitable for users of each API, and the source should have comments relevent to those editing the implementation.