Lua documentation: member functions and local vs global defines

[siegLoesch]

Hi Vladimir, first of all thanks for supplying your tools as open source! I was searching for anything to document lua code taking doxygen as base, which I am used to for C++ documentation. Currently I am in the stage of getting known to your tools in a better way and try to do that with a simple lua module file (Please see init.lua inside simpleSetModule folder in attached zipped file). Thereby I recognized two subjects:

1. If I define an object as table and add a member function luadoxyxml does not recognize the function name but takes the table name for that (see file: _luadoxyxml.out or/and open index.html inside html-final folder):

   int Set:Set(
   int setList
   );

   My expectation is:

   int Set:new(
   int setList
   );

2. In case I try to define local functions and variables luadoxyxml is ignoring them (line 10 in file: init.lua. Am I doing something wrong here?

My pipe sequence is as follows:

• luadoxyxml -o xml/index.xml --doxygen-filter init.lua |& tee luadoxyxml.out
• doxyrest --config=".../frame/doxyrest-config.lua" xml/index.xml
• sphinx-build -b html rst/ html-final/

Best regards Siegfried simpleSetModule.zip

[vovkos]

Thanks for the report! The Doxyrest Lua documentation module is not as tested as the C/C++ one. I use luadoxyxml for documenting Doxyrest frame settings, but there are no modules there. It's quite likely that luadoxyxml simply doesn't generate the proper output for module members.

As for the local items -- IIRC, they are ignored on purpose. Do you think they should be included in the documentation? Probably, the best approach would be to ignore local items by default, but have a dedicated option in doxyrest-config.lua to enable documentation for locals.

Let me know what you think.

[siegLoesch]

Thank you for your feedback! I am not really a lua expert. Though I like the language I am currently using it only for extending neovim capabilities. On the other hand I like to document code, also for local (or private) members and attributes (what can be seen as the developer view). If one only wants to use a module or library, documentation of globals is for sure enough. As usual there should be a well defined default configuration together with an option to modify it. Therefore I would follow your recommendation above as stated.

[vovkos]

I played a little bit with luadoxyxml and Lua modules, and of course it just doesn't work; it was never used like this, so I'm not surprised.

Modifications are required for it to emit the proper pseudo-C for member functions; frames probably need to be adjusted too -- so they understand that modules are not the same as tables-types (and must be put into different documentation sections).

If you have a good sample project in Lua, that would certainly help. By "good" here I mean, it should be large enough, and with modules and classes. No need for it to be "properly" documented (I just want to test the structure of pseudo-C, direct-XML, and the generated RST documentation).

[vovkos]

Last weekend I added support for Lua classes & modules; \luamodule and \luaclass commands were added to separate modules and classes from structs (internally they are just the same, i.e. Lua tables, but they are different semantically and are supposed to go to different sections of documentation).

All the forms of method declaration should work:

--! \luaclass
MyClass = {
  --! form 1
  methodFoo = function(param) 
  end
}  

--! form 2
function MyClass.methodBar(self, param)
  self.field = param
end

--! form 3
function MyClass:methodBaz(param)
  self.field = param
end

Please try it and let me know if it works for you. Both the luadoxyxml app and doxyrest frames had changed, so be sure to pull both (or use doxyrest_b, it is updated automatically).