Iris2.de

Posting about the possible documentation generation options.

LuaDoc seems to work nicely, see example here. Its customizable, but theres some "tags" missing (todo) in the code like "release" or "usage". LuaDoc (by default) does not include "source code" blocks in the documentation. At least to me it might be worth while having in there, but thats just me. Adding this feature might not be that difficult but its still one thing to do.

Natural Docs isnt specifically made for lua but as far as i can see it can work with it(?). I cant think of anything in lua that might make it impossible to use with. Havent tested this myself though, but it seems nice. Dont like the default look of the document pages though, LuaDoc seems nicer. Some user made examples here.

ROBODoc is another "not for lua but might work" alternative. Havent tested this either. The example pages in their homepage are, frankly, pretty nasty. The wiki image looks better though. Obviously, all these are configurable as far as i know. Examples here.

Some document generation system comparison page in Wiki.
http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

Internet article listing several alternatives...
http://internetducttape.com/2006/07/05/inline-source-code-documentation-language-independent/


To me any one of these would work. Im not sure if LuaDoc would make it any less of a work involved than than the other two.

Good Idea.

You should start making some tagged comments.

Maybe hagish is able to generate this docs automatically like doxygen?

thx.

Question is, which documentation system would be the best option?

i think that anything "generic" that doesn't understand lua doesn't makes sense, since that means all the info has to be written into the code manually.
And copy-pasting function-names and parameters is mind-numbing work, so it will be neglected, which makes the docs useless imho.

I think these tools does this. I think Mystiqq means optional Tags for better reading.

We should give luadoc a try and we will see what happends.

I mean, "all the info" in this case is function parameters. Even with LuaDoc you have to specify each parameter indivitually to describe them. Thats as far as the "understanding" of lua goes at least in LuaDocs case(?). Im not sure if there even is anything else to "understand" really.

For instance, look at the wiki page of ROBODoc. They allow you to pass the function declaration(?) as part of the documentation, hence you dont have to rewrite it. You still have to write the parameters descriptions etc.

Example using LuaDoc.



Bare minimum for LuaDoc is the "triple dash" line. It has to be before any function or it gets ignored. You will see the function in the "functions" list with its parameters etc. Also parameters without any descriptions are displayed.

Im not aware of any Lua specialties that would make using these "generic" doc systems any less efficient compared to LuaDoc. Cool thing about LuaDoc is that its easy to alter, simple templates even i can understand. Only thing i think is truly "bad" is the lack of the source code in the document. I mean, just showing a function and its parameters isnt exactly informative (enough) to me.

Im all for using LuaDoc, because its simple to edit and we can add the source code as a tag (or something), which we can add later (or never). To me if adding just "---" in front of the function would display functions etc. with possible source code, it would be quite good even without manually adding descriptions etc. Also one tag isnt coded yet, its the @release which would be for description for the file that would show up in the "files". The tag is used in the templates but the actual code that would "write" this tag isnt coded in.

ok, then luadoc also doesn't really understand the lua syntax.

the problem i see here is that all the systems mentioned can't even produce a function list without someone manually going through the code and tagging each function, and if not even luadoc understands the lua syntax that would mean that the "tagging" would also have to include info about the function parameters, which amounts to a lot of work if you ask me.

it's not fun to write a tag for every parameter if their names already make their meaning obvious.

example1 : -- param x : the x part of the coordinate.
i'd call that noise rather than documentation.

example2 : -- param dialog : a handle to a dialog object
also rather noise than documentation.


a examples of what i expect from an automatic documentation system (and doxygen does all that for c++ already, so it IS possible):

with no comment at all should be listed in the generated documentation without anyone having to apply tags manually.

The doc-system should be able to list the function-name and parameter-names
without anyone specifying them manually.



should result in a documentation entry with functionname, parameters, and the little comment above it.

About understanding the lua syntax :
the DocSystem should be able to group methods of the same class together, therefore it needs to understand the lua syntax a bit :

If the documentation system is generic, it relies on someone manually adding this info, which makes it pretty much useless.
It seems that luadoc doesn't do that as well, so it looks like none of the existing documentation systems is really useful.

sorry, but adding such info manually is unacceptable, as it makes maintenance a headache, and clutters the code.

so i guess i'll look into doxygen a bit to check if it can be extended, or start working on that php script to generate some useful documentation automatically, this might be useful for other projects as well.

Roger that.

Yea the current alternatives arent exactly perfect. LuaDoc seems to be the only one even remotely "lua compatible". I know PHP to some extent, i could give a hand is if its needed. Although id rather just concentrate on the shader/material/etc. if possible.

first experimental output (pseudo c++ with comments):
http://zwischenwelt.org/trac/iris/brows ... o_code.cpp

php code for that :
http://zwischenwelt.org/trac/iris/brows ... ua_api.php
http://zwischenwelt.org/trac/iris/brows ... roblib.php

generated by running

in the main dir (needs php commandline installation)

(this is not the final format of the documentation, we plan to run doxygen on that pseudocode, but it might need a little more tweaking first)

ok, docs are now online :

http://zwischenwelt.org/~hagish/irisdoc ... tated.html

(also in the wiki-navbar)

Sweet