There are no documentation standards for Ruby/Rails really (I'm working on an entry on this...so bare with me), and so I'm sort of left to my own devices when analyzing quality. The plan is to allow users to write their own analyzers and thus let them create their own quality standards, but it would be nice to include a "default" quality analyzer. The problem though is not what it should do, but how?
Quality is so subjective, that if we're to do a midline, objective analysis, a standard needs to be developed or some sort of criteria needs to be met. This entry is little more than a plea to you guys and gals: help me create one! What do you think makes good quality API documentation? I'll reconcile your responses into something workable in a future entry and that will become dcov's standard criteria set (until we decide to change it ;)). Here are a few of my ideas:
- Parameters should at least be mentioned.
- Options hash must be documented if present.
- Default values must be explained.
- A return value description should also be present, if there is a return value and it is not apparent.
- Examples! Examples! Examples!
Let me know what you'd like to see.