[Aldor-l] +++ Documentation structure

[Ralf Hemmecke]

Hello all

With this mail I want to address the documentation of ++ comments in
Aldor and everyone is invited to add his/her view or any remarks to
the following.

The goal is to come up with a Aldor Documentation Guide that specifies 
the conventions/norm used for the ++ comments.


Currently, there are two ways to document Aldor sources.

1) Write the documentation in #if ALDOC ... #endif blocks where the
contents follows the rule set by the aldoc.cls LaTeX class file.

2) Write inside ++ comments and use AldorDoc later.



Both approches have advantages and disadvantages.


Aldoc approach:

1+) Writing in LaTeX without bothering about putting ++ at the
beginning of every line certainly eases the writing process and gives
the full power of LaTeX for the documentation.

1-) The source becomes almost impossible to read when the
documentation is put in between the code lines. There is no good tool
that helps to make the code and documentation more readable by
highligthing the parts.

1-) There is redundant information. Signatures have to be written in
the documentation and may not always agree with the corresponding code
they document. So this way of documenting Aldor sources is error prone.

1-) The code is not seen by the compiler. Thus the .al library does
not anymore contain the documentation.


AldorDoc approach:

2+) Extracting the documentation is in principle possible.

2-) AldorDoc is would be a nice tool to extract documentation, but it
is incomplete and nobody seems to work on it since Yannis left.

2-) There has never been an agreement of how ++ comments should be
structured so that the resulting documentation is not much better than
writing it in ASCII. (In particular, no nice formatting or hyperlinks
could be made.)


There is definitely a need for a good documentation extraction tool.
However, such a tool cannot be written if there is no agreement on how
the contents of ++ comments should be structured.

Personally, I like the Aldoc idea of using LaTeX, but I'd rather like
to see the documentation as ++ comments. I don't like the complexity
of Aldoc: one has to remember \altype, \this, \alfunc, \alexp, \name,
etc.


The goal should be to write a nice documentation tool comparable to
JavaDoc. Before writing a tool let us start with a few specifications.

1. The documentation should appear as ++ and +++ comments so that the
compiler is able to put them into the .ao file and some program (a bit
more advanced than AldorDoc) is able to extract those comments and
puts them into a nice browser form similar to what hyperdoc (in Axiom)
used to be.

2. The ++ comments should not contain information that could be
extracted from the actual code (like, for example, the name of the
type that is described inside ++ or name and signature of functions).

3. The ++ comments should be easily readable in the .as file.

4. The markup for structuring ++ comments should be easy to learn and
easy to remember.



A Suggestion:

Although not everyone is fluent in LaTeX, I propose LaTeX for the
general markup of ++ comments. One good reason for LaTeX is that it is
very powerful. A second one is that I am about to release an
   Aldor Literate Programming Support
in a few weeks where everything between code lines IS LaTeX including
the ++ API description.


As additional markup I (actually together with Christian Aistleitner)
propose

\adtype{TYPENAME}
     markup for a category, a domain or package name, TYPENAME should
     be typeset as a link to where TYPENAME is defined. Typeset in
    verbatim mode.
\adthistype
     expands to the type most recently defined,
\adname[TYPENAME]{FUNC:SIGNATURE}
     markup for a function or a constant, FUNC appears in the text. The
     other information is used for hyperlinks. FUNC should be set in
     verbatim mode.
\adthisname
     expands to the function or constant most recently defined,
\adcode{SHORT ALDOR CODE}
     markup for very short pieces of Aldor code (oneliners),
\begin{adsnippet} .. \end{adsnippet}
     environment to set (possibly incomplete) pieces of aldor code,
     code appears in verbatim mode.
\begin{adprogram} .. \end{adprogram}
     environment to set short programs (which should be compilable),
     code appears in verbatim mode.
\begin{adusage} .. \end{adusage}
     environment to describe the usage of a function, constant
     or type,
\begin{addescription}{SHORTDESCRIPTION} .. \end{description}
     environments to describe the function, constant, type more clearly,
\begin{adseealso} .. \end{adseealso}
     environment to refer to related things,
\begin{adremarks} .. \end{asremarks}
     environment to describe particular behavior.
     ((I am not sure whether remarks should get their own environment.))

Maybe there should also be

\begin{adparameters} .. \end{adparmeters}
     environment to describe function parameters

\begin{adexceptions}
\adthrows{MyExeption} Description of \adthisexception.
\adthrows{MyOtherExeption} Description of \adthisexception.
\end{adexceptions}
     environment to describe which exceptions the function throws.


Does anybody see a need for other markup?

I hope that this mail starts a short or long discussion on this issue.

Ralf