Re: Literate Programming in Ada, AdaDoc, AdaBrowse

[Marius Amado Alves <amado.alves@netcabo.pt>]

> If there's anything special I need to be aware of about a particular 
> function, then I want it to be noted in the most obvious place. I don't 
> want to scroll down to check if perchance there might be a note about 
> this function at the bottom of the file.

Agreed. In this example there is nothing really special, but there are 
cases e.g. the infamous warning "the programmer is responsible for 
freeing this object". In those cases a *small* warning should be placed 
near the entities.

> You also removed some important information: Where does the 
> parameterless Get_Line read from? Which line does it get? Does it always 
> return the whole line, from line break to line break, or could it be 
> just part of the line in some cases? If so, which part and in which 
> cases? We can assume that the second Get_Line reads from the file we 
> pass to it, but does it otherwise work the same as the first Get_Line or 
> are there any differences? The original file answers all of those 
> questions.

All obvious answers, and so should be separate, if present at all.

1.  http://www.liacc.up.pt/~maa/files/g-io_aux.ads
2.  http://www.liacc.up.pt/~maa/files/g-io_aux-edited.ads
3.  http://www.liacc.up.pt/~maa/files/g-io_aux-notes.html

Note these are just fabricated outputs of an idealized master system for 
organizing source code with documentation. One viewable item can 
actually be the overloaded-with-comments source code file 1 which the 
tool keeps syncronized with 2 and 3. Then all views would be available 
for all tastes. (Hey, I just described a big part of my PhH hypothesis, 
Adaptive Hypertext :-)

The main (sub)thesis here was that the information required to make the 
necessary connections is there in the position of the notes in 1 and in 
the names of the formal entities. No visible special markers necessary.