Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Andre <avsaway@hotmail.com>]

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.