Re: [ANN] LuaDoc 3.0 Released

[David Manura <dm.lua@...>]

Tomas Guisasola Gorham writes:
> LuaDoc is a documentation generator tool for Lua source code.
> It parses the declarations and documentation comments in a set of Lua source
> files and produces a set of XHTML pages describing the commented declarations
> and functions....Feedback is welcome!

Another useful property of a documentation tool is that it be language neutral,
at least in a fallback case, so that a single tool can be used for a
multilanguage project (e.g. Lua and C).  POD/POD6, ROBODoc, and Natural Docs, to
name a few, have this property intentionally.

That may prevent a deep integration between the documentation tool and a
particular language, but it can be ameliorated with an extensible underlying
data model (e.g. custom header types in ROBODoc, custom header names in POD,
custom keywords in Natural Docs, or possibly the @class tag in LuaDoc) and
configurable parser.  It may require additional programmer typing too, as some
information is not inferred from the language, though for a dynamic language
like Lua it can be very difficult to reliably infer that information from static
code analysis alone and without making assumptions.

The data model typical revolves around entities that have a certain metaobject
type (e.g. function, class, method, file, process, etc.), a unique name that
allows linking between entities, possibly hierarchical relationships, an
association to some part of code (e.g. via containment in nearby comments), and
corresponding documentation, possibly divided into different sections (e.g.
synopsis, inputs/outputs, error handling, test cases, etc.)  Requirements for
formatting the documentation inside that structure are usually rather simple:
bold, fixed-width/preformatted (code), lists, paragraph breaks, and links
(though Javadoc does the full HTML thing).  The data model should allow
introspection, such as for formatting, translation, and validation.

There has been some complaints about particular documentation tools because of
syntax (e.g. POD verbosity, ROBODoc CAPS, and Natural Docs ambiguity), but
what's more important is the underlying data model because syntax can be
automatically translated, and some tools like Doxygen and Natural Docs support
multiple syntax styles.  That assumes that the syntax is formally specified,
which was my complaint about NaturalDocs.

Interestingly, I see the ROBODoc roadmap (
http://www.xs4all.nl/~rfsber/Robo/roadmap.html ) mentions "Rewrite of ROBODoc in
Lua".  That would seem to be a much more reasonable fit than doing text
processing in C.