Re: Documentation tools

[PA <petite.abeille@...>]

On Jan 05, 2005, at 20:05, Andre Carregal wrote:

> > Talking about this unfortunate JavaDoc style, perhaps you
> > might want to consider an, er, "alternative" format:
>
> By "unfortunate JavaDoc style" you are referring to the in-source 
> syntax of
> JavaDoc or the its generated HTML pages?

Both. The format is very, er, "confused". The tags (aka doclets) are 
mostly useless for most practical purposes.

> LuaDoc has a back end processor that extracts information from the 
> source
> files, and a front end processor that generates a "static site" from 
> the
> extracted information.
>
> Once you have the information structured in memory, you could generate 
> lots
> of different "sites" from it. You could also generate PDF docs for 
> example.
>
> I couldn't find an example of DyDoc syntax (I'm assuming it is also
> in-source based),

No. Source and documentation are keep separated. Documentation "stubs" 
are automatically generated based on runtime information. Then those 
stubs are use to populate the documentation content itself (e.g. the 
comments themselves). Think about it in terms of the "stubs" being 
equivalent to a header file with comments. The source code itself is 
left pristinely free of unnecessary clutter.

>  but as far as I can see, a good templating scheme should
> handle that formatting without much hassle.

Yes, that would be nice :)

> Could you please elaborate a bit?

Cheers,

PA.