caboose

It's time for another documentation project update. This week concentrated on continuing to lay down plans, with the creation of a styles and conventions page that we (and future doc writers) will do our best to adhere to. We also laid plans to create a Rails application to keep track of our Basecamp information rather than giving the public access (since someone keeps ticking off our to-do items...). Here are the patches this week:

• #7656 : ActionView::Helpers::PrototypeHelper documentation
  UPDATED I updated this patch to include documentation of all the JavaScript generated by the methods; I also went back and fixed a few errors in the original documentation and my edits.
• #7722 : ScriptaculousHelper documentation improvements
  The documentation for ScriptaculousHelper assumed (a) that the reader knew what Scriptaculous was and (b) they knew what all the parts did. This patch adds more background information, shows the javascript generated by each method, improves the README, and cleans up the grammar a little bit.

In light of the new README convention we've developed (README's for packages will contain very high level overviews with no examples, Base class documentation will have examples with very little theory and will act as jumping pages to the relevant portions of the documentation) I'm working on a new README and Base class documentation for ActionView (ActionPack) that's about 75% done; Jamie is nearly done with the ActiveRecord documentation in the same vein. Both of those patches should probably make it in next week, which will result in a hefty upgrade to the documentation of those classes/packages.

Also, in the interest of helping out this documentation project, I've developed a tool called dcov (Documentation COVerage) that will report on the documentation coverage of Ruby code files, somewhat similarly to rcov. It basically rips a lot of Ruby parsing code off of Rdoc (which rips its code off of something else ;)) and generates a report on documentation coverage of classes, modules, and methods. Right now, it merely tests for a comment, but soon one day I want to have it crawl the code and test for options hashes and then check for documentation of those, generate documentation stubs, with placeholders for parameter documentation (and eventually any usage of the options hash it can figure out), and more...but that comes with time. I'll post the Rubyforge page when it's in a state ready to be used.