Authors CurseForge

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?

No.

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.

Quote from Tekkub

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?

Ace had a parser, but the wiki's gone so that's basically gone too.

Seems that a luadoc parser is back? note haven't tried but see this Knowledge Base article.

i think they are working on some sort of autodoc sytem but am not sure it they have even started on it yet :)

It was finished and working before this thread was even started afaik.

ahh very cool for anyone else you can find documentation for it here
http://www.wowace.com/knowledge-base/docmeta-file/

Quote from yssaril

ahh very cool for anyone else you can find documentation for it here
http://www.wowace.com/knowledge-base/docmeta-file/

That's what I said :P

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.

I think Nevcairiel customized a luadoc syntax module for us since our style of coding is a lot different than what the default one was made for.

Quote from Arrowmaster

I think Nevcairiel customized a luadoc syntax module for us since our style of coding is a lot different than what the default one was made for.

Is that available to the wowace-going-public via .docmeta somehow, or was that an internal Ace3 team thing?

Its the only option when using luadoc. You can try digging through http://hg.curseforge.net/www/curseforge-documenter/mainline if you want to find out exactly what changed.

Quote from Arrowmaster

Its the only option when using luadoc. You can try digging through http://hg.curseforge.net/www/curseforge-documenter/mainline if you want to find out exactly what changed.

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?