Documentación de Rails

Este va a ser el primer post en el que critique un aspecto de Rails: su documentación. Y es que si bien el Framework en si mismo es genial, la documentación no llega al mismo nivel de excelencia. Siempre bajo mi punto de vista, claro esta.

Y es que yo, que he sido los últimos años un enamorado de Java, soy de esas personas raras dentro del desarrollo de software que valoran mucho la documentación, tanto de los productos finales, como de las APIs.

Si yo me enfrento a documentación en JAVA DOC, se exactamente que tipo de parámetros necesita un método para funcionar, las excepciones que lanza, el tipo de retorno, etc... en cambio en Rails no es asi.

Algunos de los métodos (ActiveRecord::Base.find() por ejemplo) si que están correctamente documentados, con ejemplos, etc... De echo, muchas de las clases tienen información buenísima al comienzo del documento sobre como utilizarlas. Lamentablemente esto no pasa en todas ellas. El módulo de vistas tiene algunos métodos con explicaciones de este estilo.

check_box_tag(name, value = "1", checked = false, options = {})

Creates a check box.

Esto no ayuda mucho. Personalmente me cuesta averiguar que puedo meter en options.... en este sentido, creo que es necesario progresar en la redación de la ayuda de ciertos métodos.

Bueno, no voy a seguir más, ya que no quiero criticar demasiado a Rails.