[Aldor-l] Source documentation

[Ralf Hemmecke]

On 04/25/2009 01:41 AM, Pippijn van Steenhoven wrote:
 >> as far as I can tell from the grammar in the Aldor User Guide, Doc(E)
 >> is never used in Curly(E) which is ultimately the Goal. The only
 >> place I see it used is in Piled(E). Is this an omission or am I
 >> missing anything here?

 > Actually, I missed it. CurlyContentB has it.

OK, but why is CurlyContentB introduced at all? It's the same as 'Doc'.

If I read tne grammar well then

+++ a
   +++ b
     +++ c
   +++ d
  foo(...): ... ==

makes 'a b c d' the PreDoc of 'foo'. Indentation does not matter, 
neither in piled nor in non-piled mode.

 > Also related but previously forgotten: where can doc comments be
 > and what are the semantics of these comments? Are they attached to
 > the expression, such that:
 >
 >   Foo (I : Integer) : Integer == {
 >       +++ This doc comment is attached to the following expression
 >       I := I + 1;
 >       ++ This doc comment is attached to the above expression
 >       +++ This doc comment is attached to I * I
 >       I * I
 >       ++ I * I is multiplying a number by itself (interesting, isn't
 >       ++ it?)
 >   }
 >
 > What use is a doc comment? How can one use them? More importantly:
 > what do we _want_ them to do?

Most importantly, pre and postdoc are used like

---BEGIN
+++ PreDoc for MyCat
MyCat: Category == with {
    foo: % -> ()
      ++ PostDoc for foo
}
---END

And there they could be attached to MyCat and foo, respectively with the 
obvious meaning of documenting these identifiers. The current compiler 
stores these Docs in the .ao files, but there is no program that 
actually uses them.

Yannis Chicha once started with an AldorDoc program which would extract 
these docs and produce something like Axiom's HyperDoc. But that program 
was never in a usable state.

I have, however, no idea, how one could reasonably use Pre and PostDocs 
for the expressions you have documented above. That would be a question 
to the designers of Aldor.