Re: Literate Programming in Ada, AdaDoc, AdaBrowse

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

Stephane Riviere wrote:

> just put your text before the
> procedure, function, etc...to comment...

Does AdaDoc require that the description be before the declaration, or 
can it be after too? I find it more natural to put it after, like this:

    function Synonym
      (Reference : Parameter_Name)
       return Parameter_Definition_Handle;
    --  Returns a definition which states that the parameter is
    --  an alternative name for another parameter.

    function Antonym
      (Reference   : Parameter_Name;
       Description : EAstring := Null_EAstring)
       return Parameter_Definition_Handle;
    --  Returns a definition which states that the parameter is
    --  the opposite of another parameter. It can only be used
    --  on boolean parameters.

    Illegal_Antonym : exception;
    --  A parameter is defined as an antonym of a parameter that
    --  can't have antonyms. (Only boolean parameters can have
    --  antonyms.)

This tells you first of all what is being declared (function, type, 
variable ...) and what its name is. Then it's explained what it does, 
and if parameter names are mentioned in the description, then they have 
been declared before they're referenced, just like in the code.

In my opinion, writing the description before the declaration breaks the 
text flow in about the same way as top-posting does.

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