Re: [ANN] LuaDoc 3.0 Released

["Frans Slothouber" <frans.slothouber@...>]

On 15/08/07, David Kastrup <dak@gnu.org> wrote:
> Ralph Hempel <rhempel@hempeldesigngroup.com> writes:
>
> > Miles Bader wrote:
> >>
> >> I've noticed that a lot of these "automatic" doc systems seem to
> >> yield similar results, e.g., doxygen "docs" which exhaustively
> >> "document" every function, class, and variable, but give no useful
> >> information whatsoever...
> >
> > Which is why a good source browser is useful. The source is after
> > all the best and most current documentation :-)
>
> Ths source suffers even worse from the problem: it gives information
> at the wrong scale if you want to get a view of the bug picture.

One needs information at both levels.
To understand a program you need the big picture and at times
detailed information about the individual functions, classes, variables
and other program artifacts (API documentation).

To create the latter tools like DoxyGen, ROBODoc, JavaDoc, etc
are well suited.   Because they keep the documentation of these
artifacts close to the artifacts there is a much higher chance they
are kept up to date.

To create a big picture document these tools are not at all suited.
Big picture documents need a story line. A story line  is very hard
to build from little pieces of documention scattered all over the source
code.   Big picture documents also need figures and diagrams. These
are also hard to make in those tools.  (At least they are in the tool
I maintain ROBODoc.)

What is a better solution is to have a big picture document written in
a proper text-editing system,  Word, LaTeX, DocBook, etc,
and to have a separate document with the API documentation generated
with one of these tools.

If the API is small it can be included as a separate chapter in the big-picture
document.   But usually API documentation is so big it is pointless to
put it in a big picture document.  Also API documentation changes much
more frequent than the big picture document.

The only tool that allows you to put both the big picture and detail information
in the source code are literate programming tools, such as cweb or nuweb.
But these work in such a different way that they do not integrate well with
debuggers and editors, or IDEs.

Have fun,
Frans