awestruct/awestruct — Issue #86: Adopt TomDoc for documentation
Author: mojavelinux
Created: 2012-03-08 00:29:26+00:00
State: open

According to my own observations and the ohloh analyzer, Awestruct has a low number of comments. I think we can do better, especially in the extensions. Besides, it's not that much extra work thanks to TomDoc.

The developers at GitHub have found a way to make code documentation much more lightweight. Details are here:

http://tom.preston-werner.com/2010/05/11/tomdoc-reasonable-ruby-documentation.html

TomDoc works because it answers the "why" instead of the "what". Why do you have this code instead of what does this code do. That helps answer the question of "Should I document an attribute accessor?" The answer would be something like "Yes it's an accessor, we get that part. Why is it being exposed?"

Zach Holdman provides some nice advice on code documentation in his blog:

http://zachholman.com/posts/documentation/

By adopting TomDoc, and a commitment to do better at documentation, I think we can get a reputation for having thorough documentation.

I want to avoid a meta-issue like "add more code documentation", so by adopting a model, hopefully the rest will just happen (or we can file separate issues for specific files).