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 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!news2.google.com!proxad.net!feeder2-1.proxad.net!news9-e.free.fr!not-for-mail
Date: Tue, 12 Oct 2004 01:32:00 +0200
From: Lionel Draghi <Lionel.nospam.Draghi@Ada-France.org>
User-Agent: Mozilla/5.0 (X11; U; Linux i686; fr-FR;
 rv:1.7.3) Gecko/20041007 Debian/1.7.3-5
X-Accept-Language: en-us, it
MIME-Version: 1.0
Newsgroups: comp.lang.ada
Subject: Re: Literate Programming in Ada, AdaDoc, AdaBrowse
References: <2sqmccF1oit5sU1@uni-berlin.de>
	<ckavmo$2v3$1@news6.zwoll1.ov.home.nl>
 <mailman.260.1097423011.390.comp.lang.ada@ada-france.org>
In-Reply-To: <mailman.260.1097423011.390.comp.lang.ada@ada-france.org>
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit
Message-ID: <416b17ef$0$311$626a14ce@news.free.fr>
Organization: Guest of ProXad - France
NNTP-Posting-Date: 12 Oct 2004 01:32:00 MEST
NNTP-Posting-Host: 82.65.180.151
X-Trace: 1097537520 news9-e.free.fr 311 82.65.180.151:34228
X-Complaints-To: abuse@proxad.net
Xref: g2news1.google.com comp.lang.ada:5060
Date: 2004-10-12T01:32:00+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. 
This is just an absolutly perfect example of why the comments should not 
repeat what is already in the code :-)

On the other hand, if you have to comment about a special parameter 
semantics, parsing the whole Ada code won't help catching a discrepancy.

-- 
Lionel