Commentable documentation

[Sairon]

As a webdev I've often found myself browsing the PHP documentation at http://www.php.net. What's really cool about the PHP documentation apart from being really detailed and awesome is that every section of it can be commented. This is an excellent way not only to group small bits of useful code with its relevant function calls, but also a great way for clarification and mention of gotchas.

Using and encouraging the same sort of documentation for OGRE I think would create a much more helpful and detailed reference. It could also become a great way for the developers to see which parts of the code base which might need refactoring for clarification purposes.

[Horizon]

That's an interesting idea. However, it will probably be hard to combine that with the doxygen generated documentation.

[Klaim]

I think it's not really adapted to Ogre since it have a lot more often new code interface breaking releases than PHP.
The comments would certainly be wrong one year after it have been published.

And the wiki is enough i think.