LEGO wrote:
The docbook files have a description of the API and are generated from
comments in the code using wslua/make-doc.pl, I did not knew about
doxygen, I'll take a look into it.
It takes a similar approach, doxygen takes specially formatted source
code comments and generates documentation out of it.
It's common in some open source applications to use it especially for
API documentation - I've added some of that comments to the WS sources.
However, I don't know if doxygen supports lua well (I only used it for
C), so your approach of using a perl script for it might be the way to go.
My only concerns was to create the API docs by hand which to my
experience just don't work in the long run.
The wiki pages is out of sync, I'll leave just examples and poiters to
documents about Lua. They are useless as such...
Well, very outdated docs - leading to the wrong way - are even worse
than no docs at all ...
As far as documentation goes I'm going to produce a set of examples
and a reference manual generated from the code.
Sounds good.
Should the generated docbook files be created directly in docbook/ ?
Depends.
We currently have:
- the user's guide (has it's own dirs)
- the developer's guide (has it's own dirs)
- the release notes (single file in docbook/)
If the lua docs will be a single xml file with no graphics it should
reside in docbook/.
If it contains more files, e.g. some screenshots or alike - or if you're
planing to add such later, it should go into it's own dir, e.g.
docbook/lua or such.
Regards, ULFL