Iris2.de

Iris2-Forum
It is currently Thu Mar 28, 2024 9:34 am

All times are UTC




Post new topic Reply to topic  [ 11 posts ] 
Author Message
PostPosted: Sun Nov 18, 2007 6:33 pm 
Offline
Power User
User avatar

Joined: Wed Jun 08, 2005 1:22 pm
Posts: 119
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.


Top
 Profile  
 
 Post subject:
PostPosted: Sun Nov 18, 2007 9:56 pm 
Offline
iris2-developer
User avatar

Joined: Mon Aug 09, 2004 12:20 pm
Posts: 1431
Good Idea.

You should start making some tagged comments.

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

thx.


Top
 Profile  
 
 Post subject:
PostPosted: Mon Nov 19, 2007 4:18 pm 
Offline
Power User
User avatar

Joined: Wed Jun 08, 2005 1:22 pm
Posts: 119
Question is, which documentation system would be the best option?


Top
 Profile  
 
 Post subject:
PostPosted: Mon Nov 19, 2007 5:46 pm 
Offline
iris2-developer
User avatar

Joined: Tue Apr 18, 2006 10:28 pm
Posts: 823
Location: Munich, Bavaria, Germany
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.


Top
 Profile  
 
 Post subject:
PostPosted: Mon Nov 19, 2007 6:34 pm 
Offline
iris2-developer
User avatar

Joined: Mon Aug 09, 2004 12:20 pm
Posts: 1431
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.


Top
 Profile  
 
 Post subject:
PostPosted: Wed Nov 21, 2007 3:02 pm 
Offline
Power User
User avatar

Joined: Wed Jun 08, 2005 1:22 pm
Posts: 119
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.

Code:
--Clamp value to range
--@param x
--value to clamp
--@param v1
--first clamp range value
--@param v2
--second clamp range value
--@return Clamped value
--@see FunctionNameHere
function Clamp(x, v1,v2)
   local vmin,vmax = math.min(v1,v2), math.max(v1,v2)
   if (x < vmin) then return vmin end
   if (x > vmax) then return vmax end
   return x
end


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.


Top
 Profile  
 
 Post subject:
PostPosted: Wed Nov 21, 2007 3:33 pm 
Offline
iris2-developer
User avatar

Joined: Tue Apr 18, 2006 10:28 pm
Posts: 823
Location: Munich, Bavaria, Germany
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):

Code:
function CrossProduct (x1,y1,z1,x2,y2,z2) ... end
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.

Code:
--- call only after OgreInit
function DoFuncy (x,y,z)


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 :
Code:
function gMobilePrototype:Update (mobiledata,equipmentdata) ....

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.


Top
 Profile  
 
 Post subject:
PostPosted: Wed Nov 21, 2007 6:18 pm 
Offline
Power User
User avatar

Joined: Wed Jun 08, 2005 1:22 pm
Posts: 119
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.


Top
 Profile  
 
 Post subject:
PostPosted: Fri Nov 23, 2007 12:34 am 
Offline
iris2-developer
User avatar

Joined: Tue Apr 18, 2006 10:28 pm
Posts: 823
Location: Munich, Bavaria, Germany
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
Code:
php generate_lua_api.php > lua_api_pseudo_code.cpp

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)


Top
 Profile  
 
 Post subject:
PostPosted: Fri Nov 23, 2007 10:28 pm 
Offline
iris2-developer
User avatar

Joined: Tue Apr 18, 2006 10:28 pm
Posts: 823
Location: Munich, Bavaria, Germany
ok, docs are now online :

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

(also in the wiki-navbar)


Top
 Profile  
 
 Post subject:
PostPosted: Fri Nov 23, 2007 11:19 pm 
Offline
iris2-developer
User avatar

Joined: Mon Aug 09, 2004 12:20 pm
Posts: 1431
Sweet :)


Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 11 posts ] 

All times are UTC


Who is online

Users browsing this forum: No registered users and 1 guest


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
cron
Powered by phpBB® Forum Software © phpBB Group