LÖVE

raidho36 wrote:Regarding correctness, an automatic documentation generator should be used for that - most places already include basic header documentation.

Newer C++ classes in LÖVE's codebase tend not to have such documentation, partly because the exposed Lua API does not usually match the C++ methods for non-trivial functions (and if we made it do that, we'd be forcing C++'s language design on a Lua API). We prefer to not write the documentation in-line in the codebase.

slime mentioned out-of-date documentation, which made me think: if you're making documentation for LOVE, consider mentioning the current LOVE version at the time the documentation was last updated or reviewed. It may still become out-of-date, but at least the reader can tell sooner.

I'm reminded of the Dwarf Fortress wiki. Every time a major update is published, they effectively create a new wiki each time by copy-pasting the old one, and adding a little box that says something like "this was automatically copypasted, if it's current you can go ahead and remove this notice"
It makes it obvious when somebody needs to put in the elbow grease to update the wiki, and it's a lot easier to follow IMO than "added/removed in 0.X.0"

example: http://dwarffortresswiki.org/index.php? ... did=213191

alloyed wrote:I'm reminded of the Dwarf Fortress wiki. Every time a major update is published, they effectively create a new wiki each time by copy-pasting the old one, and adding a little box that says something like "this was automatically copypasted, if it's current you can go ahead and remove this notice"
It makes it obvious when somebody needs to put in the elbow grease to update the wiki, and it's a lot easier to follow IMO than "added/removed in 0.X.0"

example: http://dwarffortresswiki.org/index.php? ... did=213191

No, because people still use older versions; how would you keep track of that without deleting the stuff pertaining to older versions?
I'd rather have this than have 500 articles titled "love.graphics.draw_(x.y.z)[_(language)]", or having 500 wikis that desync. That's worse imo.

I maintain that using wikimedia for documentation is not the best tool for the job, and that the documentation and any "manual" or tutorials etc should be separate.