From mboxrd@z Thu Jan  1 00:00:00 1970
X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me
X-Spam-Level: 
X-Spam-Status: No, score=-0.3 required=5.0 tests=BAYES_00,FREEMAIL_FROM,
	REPLYTO_WITHOUT_TO_CC autolearn=no autolearn_force=no version=3.4.4
X-Google-Thread: 103376,887292c91e10d3fd
X-Google-NewGroupId: yes
X-Google-Attributes: gida07f3367d7,domainid0,public,usenet
X-Google-Language: ENGLISH,ASCII-7-bit
Path: 
 g2news2.google.com!postnews.google.com!glegroupsg2000goo.googlegroups.com!not-for-mail
From: Marco <prenom_nomus@yahoo.com>
Newsgroups: comp.lang.ada
Subject: Re: Ada documentation tools.
Date: Mon, 20 Dec 2010 05:02:10 -0800 (PST)
Organization: http://groups.google.com
Message-ID: 
 <4f1d24ec-79df-4e12-8e40-11e591223e82@glegroupsg2000goo.googlegroups.com>
Reply-To: comp.lang.ada@googlegroups.com
NNTP-Posting-Host: 67.1.11.7
Mime-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1
X-Trace: posting.google.com 1292850130 28556 127.0.0.1 (20 Dec 2010 13:02:10
 GMT)
X-Complaints-To: groups-abuse@google.com
NNTP-Posting-Date: Mon, 20 Dec 2010 13:02:10 +0000 (UTC)
In-Reply-To: <sZqdnewQpeDSXnzRRVn_vwA@giganews.com>
Complaints-To: groups-abuse@google.com
Injection-Info: glegroupsg2000goo.googlegroups.com; posting-host=67.1.11.7;
 posting-account=WITAxQkAAAAHjnLda9Lofpqp8mERTWL4
User-Agent: G2/1.0
Xref: g2news2.google.com comp.lang.ada:17033
Date: 2010-12-20T05:02:10-08:00
List-Id: <comp.lang.ada>

On Monday, November 15, 2010 4:33:19 PM UTC-7, Peter C. Chapin wrote:


> Speaking of Doxygen... one thing that I rather like about it is that it
> allows you to include comments on either the declaration or the
> definition of a function. The Ada tools I've seen so far believe that
> all "documentation" comments should appear in the specification. I agree
> that is logically where they should go but from a maintenance point of
> view it can be nice to have the documentation for a subprogram right
> where one spends time editing that subprogram. I understand this invites
> confusion between documentation for users vs documentation for
> implementers.

Whitebox vs Blackbox is important - comments on the algorithm used for example belong in the body not the spec since it could change without affecting the caller