2012-01-08 12 views
5

Ayer I answered a question sobre cómo funciona attr_accessor. Quise hacer un enlace a la documentación del método, pero para mi sorpresa, es didn't show up en ruby-doc.org. ¿No debería estar documentado en Module.html? Estoy bastante seguro de que estuvo allí una vez, ya que ri Module#attr_accessor y APIDock muestran la documentación correcta y Google search muestra esta página entre los primeros resultados.¿Dónde están los documentos oficiales para `attr_accessor` y otros métodos de` Module`?

Ahora me pregunto: ¿Por qué eliminaron la documentación de este método muy común (y también la de otros métodos importantes como Module#define_method)? ¿Y dónde está la documentación oficial para esos?

+0

Sí, lo he buscado también. Aquí hay un sitio increíble que prefiero sobre la documentación cuando quiero aprender algo: http://www.rubyist.net/~slagell/ruby/accessors.html. Estoy bastante seguro de que no hay documentación en ruby-doc.org porque: http://ruby-doc.org/search.html?cx=011815814100681837392%3Awnccv6st5qk&q=attr_accessor&sa=Search&cof=FORID%3A9 – itdoesntwork

Respuesta

5

decidí escribir un correo electrónico a los encargados del mantenimiento de ruby-doc.org y le preguntó ellos sobre la documentación faltante de estos métodos. Recibí la siguiente respuesta:

Son métodos privados, y de forma predeterminada no aparecen en la salida de rdoc.

Ésta es una situación desafortunada, ya que a diferencia de la mayoría de los métodos privados (cuyo uso debe evitarse, ya que por lo general son de aplicación detalles, no parte de una API pública) attr_ * y tales son realmente la intención para uso general.

No estoy seguro de cuál es la solución correcta aquí.

James

En un segundo mail:

He hablado de ello con Greg Brown, Eric Hodel, y algunos otros que han estado trabajando para mejorar las rdocs de 1,9.

El consenso general es que muestra todos los métodos privados sería una mala idea en que sería (tal vez sin darse cuenta) animar a la gente a métodos de uso de que son susceptibles de cambiar de una versión menor a la siguiente. Pero apreciaron que los métodos privados como attr_ * son, mientras que son técnicamente privados, se utilizan en una especie de forma pública y que los documentos deben aparecer de forma predeterminada.

Intenté establecer algunas directivas rdoc en el código para éstas en el código fuente C pero no tuvo ningún efecto.Parece que lo que se necesita es de alguna manera adicional para indicar que, de manera conductual, un método es privado, pero para documentos es público.

Tendré que dar seguimiento a esto para ver si el equipo de mejora de doc. ha encontrado algo.

Gracias,

James Britt

Véase también this thread para obtener más información y otra declaración de James respecto a este tema. En este hilo, también dice que la directiva :doc: generalmente disponible en RDoc para solucionar este problema exacto en el código de Ruby no parece funcionar para la documentación de C-level.

Esta respuesta parece sensata. Quizás lo cambien en el futuro.

+0

Gracias por dar seguimiento. –

+1

¡Hola, ese soy yo! Empecé ese hilo debido a una pregunta de Desbordamiento de Pila también. –

+0

@Andrew: Hola, qué casualidad. Es un mundo pequeño, ese Ruby :) –

1

apidoc version

me sale todo desde allí.

Ah, usted editó la pregunta.

Sí, es debería estar allí, pero parece que muchos de los métodos C ya no existen.

+0

Sé de eso, pero APIDock no es documentación oficial, ¿verdad? ¿Sabes por qué no está en rubydoc.org? –

+0

@NiklasBaumstark Se genera a partir de la misma fuente. Personalmente, ejecuto documentos localmente ahora usando [sdoc] (https://github.com/voloko/sdoc) para no tener que preocuparme por eso. –

+0

Lamento que haya editado el título después de responder, ahora refleja las preguntas que estaban en mi texto desde el principio. –

Cuestiones relacionadas