This is something we (I) want to improve on, sure. http://mootools.fakedarren.com/docs/Element/Element/
One of the biggest requests from our survey<http://mootools.net/blog/2010/12/05/mootools-survey/>was that people would like to see inline demos, so this integrates the demo runner <http://mootools.net/demos/> too. I've not really gone into this too much; I am using XSL to transform the current markdown docs we have, into other forms, because I think we're actually pretty happy with the simplicity of using markdown for our docs. We could add more structure to our markdown but I doubt we would be able to convince everyone to move into another format. But the general thought behind it is that if you were to go to a page like Fx.Tween <http://mootools.fakedarren.com/docs/Fx/Fx.Tween> you get a nice summary of the methods available, and you than then delve in further to the methods that interest you, and with demos we can make it easier to scan a class or module, and give more detail for specifics. Sometimes some of the details get lost because there is too much information on any one page. The git repository can be found here<https://github.com/fakedarren/mootools-docs> . With regards to comments.....this has been discussed endlessly before. It sounds great but the reality is not as rosy as it seems. It would need heavily moderating to be of real use; you could have a system whereby comments only exist for a couple of weeks; if the comment is really insightful, we adjust the documentation accordingly. But just look at the PHP documentation; yes there is some great stuff in the user comments. There is also some terrible stuff in there. But as arian says we already have the ability for any and all users to comment and / or adjust our documentation. It's all freely available on github <https://github.com/mootools/mootools-core/tree/master/Docs>. We welcome all and any feedback. This is something that I wish to improve on - free time has been an issue lately - so this thread is of great interest to me, keep the comments coming! Cheers Darren
