truthfully coders that document as they go are rare..
ones that think about configuration and reuse are equally rare.
documentation always falls on the "NOT ENOUGH TIME" block of things to do. There was a wiki about ca's stuff and I was going to fill it out for chili but then I stopped caring when I realized I would be documenting other people's projects when my own had so much work aka "NOT ENOUGH TIME"
But that's pretty much the point why i'm advocating luadoc here.
There's plenty of comments in the code - and most coders that are not cowboys seem to leave plenty of those. The comments in Chili code also seem to follow some format conventions (such as starting with --// whereas lua syntax only needs --).
Distilled to bits, the idea is that if the format for the comments was a bit different, these same comments could be used to auto-generate the documentation.
So 1) it wouldn't take any notable extra time on the coder's part (since the comments are there anyway and the docblock is essentially a comment with stricter format) , and
2) it would not take more time than 500 ms per iteration to maintain the documentation relevant (as opposed to the 'need to manually write up documentation in wiki).
Of course, such documentation would not be very juicy and will probably be very-very dry (well look at what your typical javadoc pops out), but it would be something to start with (at the very least, providing the listing of what you can use without having to rtfs each relevant file).
Anyway, if i get some more spare time this week, i'll probably try to inflict some luadoc on chili and just see what happens. Running luadoc on the current code state doesn't yield anything useful at all, so maybe lua's fluid nature is just too resistant to doc-generation this way (so far of what i've met, even undocumented javascript vs jsdoc have yielded better results - so it just might be that example&rtfs is the better option altogether).
