Is there any standard or convention for documentation-style code comments for Lua in general, or for WoW addons in particular? I'm thinking mostly of comment headers for library functions, to identify and explain their parameters and return values. For example I notice a lot of Ace libraries use someting like "-- @argname [type] desc".
Also, is there any connection between wowace's wiki and project pages? i.e. if I comment my code according to whatever scheme, can I have basic documentation auto-generated on the wiki based on those comments? Or are they totally separate and I'll have to write up the documentation by hand?
If you use good clear variable names, your code should be "self documenting" and you only need to comment at those "WTF" spots. The only time you need to go heavy on the comments is for documenting the API inside a lib.
I actually did find the luadoc project on google before posting, but at first glance I didn't realize it also specified a 'default' comment syntax -- the first few sections I read on their site seemed to talk all about how to write your own modules to define your own comment syntax, which isn't what I wanted.
And anyway, WoW addon lua is a slightly different community than lua in general, so I wanted to know if the folks here had adopted a different convention.
Thanks for the docmeta link, when I get to uploading my lib I think that'll help a lot.
So, to clarify, if I put "type: luadoc" in a .docmeta file in a wowace project, it will run nev's module via luadoc, instead of the "generic" one documented at luadoc's site?
Also, you could take a look on the last Ace3 revision, Nevcariel added several luadoc comments and .docmeta file. The result is found in the Ace3 projet pages.
Also, is there any connection between wowace's wiki and project pages? i.e. if I comment my code according to whatever scheme, can I have basic documentation auto-generated on the wiki based on those comments? Or are they totally separate and I'll have to write up the documentation by hand?
If you use good clear variable names, your code should be "self documenting" and you only need to comment at those "WTF" spots. The only time you need to go heavy on the comments is for documenting the API inside a lib.
That is what I'm doing. :)
So, were the function comment headers in the Ace3 libs based on any particular scheme or style, or just made up by whoever coded the function?
http://luadoc.luaforge.net/
http://www.wowace.com/knowledge-base/docmeta-file/
That's what I said :P
google FTW :D
And anyway, WoW addon lua is a slightly different community than lua in general, so I wanted to know if the folks here had adopted a different convention.
Thanks for the docmeta link, when I get to uploading my lib I think that'll help a lot.
Is that available to the wowace-going-public via .docmeta somehow, or was that an internal Ace3 team thing?
So, to clarify, if I put "type: luadoc" in a .docmeta file in a wowace project, it will run nev's module via luadoc, instead of the "generic" one documented at luadoc's site?
Also, you could take a look on the last Ace3 revision, Nevcariel added several luadoc comments and .docmeta file. The result is found in the Ace3 projet pages.
http://www.wowace.com/projects/ace3/files/55-r714/