# Re: Why Class decls and API docs don't Match

**URL:** <https://www.ruby-forum.com/t/re-why-class-decls-and-api-docs-dont-match/72917>\
**Category:** Ruby\
**Created:** [October 19, 2006, 10:03pm UTC](https://www.ruby-forum.com/t/re-why-class-decls-and-api-docs-dont-match/72917 "2006-10-19T22:03:14Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![phrogz](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/2acd7d/32.png) [@phrogz](https://www.ruby-forum.com/u/phrogz)\
**Post date:** [October 19, 2006, 10:03pm UTC](https://www.ruby-forum.com/t/re-why-class-decls-and-api-docs-dont-match/72917/1 "2006-10-19T22:03:14Z")

</div>

From: removed\_email\_address@domain.invalid [[mailto:removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid)]

> As such, Ruby designers might have more carefully considered how’d  
> they expect programmers to understand Ruby libraries for that’s how  
> Ruby development of Ruby programs would proceed.

I 100% agree, and I think it applies more generally than just Rails. To  
restate what you’re saying, documentation is MORE important in Ruby than  
other languages, because runtime shenanigans and dynamic typing make it  
hard(er) for a documentation tool to figure out what’s going on and  
provide useful feedback.

Documentation in general has been one of Ruby’s sore points for a long  
time (though getting better all the time thanks to many dedicated  
volunteers). For example, look at the number of libraries included with  
the Ruby Standard Library[1] that are listed in italics[2]. The XSD  
library, for instance, looks like it might be quite useful…but I have  
no idea because all that exists are the standard documents.

> I will stop here. I don’t want to say more or less. I don’t want to  
> start discussing dynamic v. static typed languages either.  
> All I have done is identify a single area of Ruby which requires  
> some continuous improvement. In working with Ruby and Rails for about  
> one week in some detail, this is the only serious qualm I have.

And even though I don’t work with rails much, in general I want to thank  
you for your persistence in stressing this problem. It’s very difficult  
for any who have worked with something for a moderate amount of time to  
see it with fresh eyes. Explicit mentions of all irritations encountered  
when first playing with Ruby are, in some cases, the only way the  
problem will get noticed and possibly corrected.

“Misfit provides an incentive to change; good fit provides none.”[3]  
Even if you don’t propose a solution to the problem, or intend to act  
upon it yourself, it’s helpful to know what’s bothering you. (Who knows  
how many others may be similarly bothered.)

That said…if you DO want the problem solved soon, you may take it upon  
yourself to keep track of each documentation flaw you find and either  
contact the code maintainers, or fix the problem yourself and submit a  
patch. Many hands make light work, and all that.

[1] [RDoc Documentation](http://www.ruby-doc.org/stdlib/)  
[2] indicating less-than-ideal documentation  
[3] [Iterative Design By Flaw Eradication](http://phrogz.net/nodes/criticismwithoutasolution.asp)