Ruby core documentation quality

Question

Soy relativamente nuevo en Ruby y tengo un tiempo limitado, por lo tanto, pruebo cosas simples. Recientemente necesité crear un archivo y porque soy un vago como el infierno, corro hacia Google. El resultado:

File.open(local_filename, 'w') {|f| f.write(doc) } 

La culpa es mía, es muy sencillo, debería haber hecho yo mismo. Luego quise comprobar qué magia de rubí ofrecen los métodos de la clase File o si hay alguna 'simplificación' al invocar esos métodos, así que me dirigí a la documentación here y revisé la clase File.

• 1.8.6 documentación me presenta "ftools.rb: herramientas adicionales para la clase de archivo" en la clase 'Archivo', que no es lo que estoy buscando.
• 1.8.7 la documentación parece estar bien para la clase 'Archivo', hay una gran cantidad de métodos. Excepto 'abierto'.
• 1.9 documentación finalmente me muestra el método 'abierto'.

Y tuve un recorrido casi igual con Net :: HTTP.

¿Exagero cuando pienso que la buena documentación de Turbo Pascal 7.0 estaba mejor organizada que la documentación de Ruby en este momento? ¿Hay alguna otra fuente para que los no iniciados recojan conocimiento? ¿O es posible que acabe de caer en un agujero para la documentación y que el resto esté súper brillante, de cinco estrellas organizado?

Gracias

Answer 1

Hay que recordar que Ruby es un lenguaje orientado a objetos, y una gran cantidad de objetos de la biblioteca estándar, se construyen en la parte superior de otros objetos. Además, muchos están extendidos por módulos, que agregan nuevas funcionalidades.

Por lo tanto, en la documentación necesita ver en qué cosas se construye un Objeto. En el caso de File, está construido sobre el IO, que tendrá mucha de la funcionalidad que esperaría encontrar en una clase estándar de "archivo".

Acepto que parte de la documentación de Ruby es inconexa. Creo que es importante obtener un buen libro; Recomiendo el que llamamos "The Pickaxe Book", también conocido como "Programming Ruby". Hay muchos otros buenos libros, junto con buena documentación en línea, pero este es un gran libro de visitas. La [primera edición] está disponible de forma gratuita en línea; Está un poco desactualizado pero sigue siendo útil.

Recomiendo navegar a través de some of the other questions similar to this en SO para obtener más sugerencias.

También mantengo enlaces abiertos a Ruby 1.9's Core y Keyword documentos. Y, finalmente, la parte superior de Ruby-Docs site apunta a mucha información buena, aunque hay que prestar atención a la versión para la que están los documentos.

Por último, no ignore la ayuda incorporada: ri en la línea de comandos es una fuente rápida de información en su propia máquina que debe contener documentación para el núcleo y biblioteca estándar, además de todas las gemas que tiene instaladas . ri open le hubiera dicho que se definieron todos los lugares "abiertos". ri File.open le habría dado mucha información sobre ese comando.

---

Cuando comencé con Ruby, el mayor impedimento para aprender el idioma era la documentación.Todavía me resulta mucho más fácil obtener información sobre Perl y Python, y siento que Ruby debería usarlos como ejemplos. Sin embargo, eso no cambia mi placer de usar Ruby. Es un gran lenguaje y una vez que supero la barrera inicial me gusta más y más.

@phoffer recomienda RubyDoc.info en el comentario anterior. No había visto ese sitio, pero se ve bien. Me gusta que muestre lo que hereda claramente una clase.

Answer 2

Tiene razón, hay un error en la documentación previa a la 1.9 con respecto a File#open.

Hay un open documentado bajo Kernel, y sí, se puede decir que, de hecho, File.open como usted señaló, sólo que no se documenta ya sea en File o en IO.

Mi consejo es simplemente use 1.9 docs ...

Answer 3

Mi versión actual es rubí 2.0.0 y 4.0.1 RI (RI -v). He estado dando tumbos con el mismo problema en el que escribo ri File.open => "Nada sabe sobre File.open"

Después de la flagelación internet me encontré con este código Source

gem rdoc --all --ri --no-rdoc 

La página es también una buena lectura de por qué debería usar ri en lugar de google.

Editar: El código solucionó el rendimiento "No se conoce nada sobre File.open". Lleva tiempo instalarlo, así que abra una nueva pestaña.