Re: Literate Programming in Ada, AdaDoc, AdaBrowse

["Björn Persson" <spam-away@nowhere.nil>]

Lionel Draghi wrote:

> 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.

But at least it causes both "FTime" and "SysTime" to be carried over to 
the document, making the discrepancy visible. If only "FTime" appeared 
in the document, anyone trying to use the document would get strange 
compilation errors, and only when in desperation they resorted to 
reading the code would the reason be revealed.

-- 
Björn Persson                              PGP key A88682FD
                    omb jor ers @sv ge.
                    r o.b n.p son eri nu