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=-1.9 required=5.0 tests=BAYES_00,FREEMAIL_FROM
	autolearn=ham autolearn_force=no version=3.4.4
X-Google-Thread: 103376,81054609038e88e3
X-Google-Attributes: gid103376,public
X-Google-Language: ENGLISH,ASCII-7-bit
Path: 
 g2news1.google.com!news1.google.com!news.glorb.com!news2.telebyte.nl!newshub2.home.nl!newshub1.home.nl!home.nl!not-for-mail
From: Andre <avsaway@hotmail.com>
Newsgroups: comp.lang.ada
Subject: Re: Literate Programming in Ada, AdaDoc, AdaBrowse
Date: Sun, 10 Oct 2004 20:04:27 +0200
Organization: @Home Benelux
Message-ID: <ckbtjc$eog$1@news6.zwoll1.ov.home.nl>
References: <2sqmccF1oit5sU1@uni-berlin.de>
	<ckavmo$2v3$1@news6.zwoll1.ov.home.nl>
 <mailman.260.1097423011.390.comp.lang.ada@ada-france.org>
NNTP-Posting-Host: cp538812-a.venra1.lb.home.nl
Mime-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
X-Trace: news6.zwoll1.ov.home.nl 1097431468 15120 84.30.194.114 (10 Oct 2004
 18:04:28 GMT)
X-Complaints-To: usenet@corp.home.nl
NNTP-Posting-Date: Sun, 10 Oct 2004 18:04:28 +0000 (UTC)
User-Agent: Mozilla Thunderbird 0.8 (Windows/20040913)
X-Accept-Language: en-us, en
In-Reply-To: <mailman.260.1097423011.390.comp.lang.ada@ada-france.org>
Xref: g2news1.google.com comp.lang.ada:5004
Date: 2004-10-10T20:04:27+02:00
List-Id: <comp.lang.ada>

Stephen Leake wrote:
> Andre <avsaway@hotmail.com> writes:
> 
> 
>>I think you need to keep it simple (as many of the replies also state)
>>Here a sample of how I write down my comment in the source code.
>>
>>    --  .Operation: Put a date-time in a string
>>    --  .Preconditions:
>>    --   .in: FTime, the date-time
>>    --  .Semantics:
>>    --   Format the date-time in yyyy-mm-dd hh:mm:ss.mmm
>>    --  .Postconditions:
>>    --   .return: a string with the date-time
>>    function Date_As_Str
>>       (SysTime : SYSTEMTIME)
>>       return String;
> 
> 
> This is an absolutly perfect example of why the documentation
> generator needs to parse the full Ada code. What is the name of the
> parameter? The document says "FTime", the code says "SysTime". 
> 
> I don't trust _anyone_ to maintain comments like this. That's what
> tools are for!
> 

This happens when code, including its comments, is copied.

But Stephen how do you want the couple the description with its 
parameter in an automatic way? This example is probably unneccessary 
comment, the name is self explaning, but that is not always the case.

By number (in this sample 1) goes also wrong when a parameter is added.

The only thing which could be done is check the given comment with the 
actual function prototype and generate errors.