Convenciones de comentarios de funciones en R

Question

Soy bastante nuevo en R, y he estado definiendo algunas de mis funciones en archivos de script. Tengo la intención de que otros los reutilicen más adelante, y no puedo encontrar ninguna guía sobre la función R que comente las convenciones. ¿Hay alguna manera de hacer que help("my_function_name") muestre ayuda? Si no, ¿acabo de documentar la función en el archivo de secuencia de comandos, de modo que alguien tenga que imprimir (o abrir la fuente de) un script para ver los comentarios?

Gracias,

Hamy

Answer 1

La manera canónica de documentar sus funciones y hacerlas accesibles para otros es hacer un paquete. Para que su paquete pase las comprobaciones de compilación, debe proporcionar archivos de ayuda suficientemente detallados para cada una de sus funciones/conjuntos de datos.

Salida http://cran.r-project.org/doc/manuals/R-exts.html#Creating-R-packages

Esta entrada de blog de Rob J Hyndman era muy útil y uno de los más fáciles para mí seguir: http://robjhyndman.com/researchtips/building-r-packages-for-windows/

He empezado a utilizar roxygen para ayudar en la toma de & paquetes de compilación como en los últimos tiempos: http://roxygen.org/

¡Hay muchos recursos y personas para ayudar cuando tenga preguntas!

Answer 2

Usted tendrá que poner las funciones en un paquete (que hace la función de portar realmente fácil). Escribí un short post sobre esto hace un tiempo con enlaces (espero que todavía funcionen) a algunos documentos relevantes que amplían el tema.

Puede generar archivos de ayuda "sobre la marcha" usando roxygen, inlinedocs.

Answer 3

Otra alternativa (y la más baja) alternativa que puede considerar son las funciones comment() y attr() para agregar algunos metadatos a sus funciones. He aquí una rápida y tonto ejemplo:

FOO <- function(x,y) { 
x + y 
} 

attr(FOO, "comment") <- "FOO performs simple addition" 

#This can be arbitrary. "comment" is special. see ?comment for details. 
attr(FOO, "help") <- "FOO expects two numbers, and it will add them together" 

entonces usted puede ver todo lo relacionado con FOO utilizando attributes():

> attributes(FOO) 
$source 
[1] "function(x,y) {" " x + y "   "}"    

$comment 
[1] "FOO performs simple addition" 

$help 
[1] "FOO expects two numbers, and it will add them together" 

O extraer partes específicas:

> attr(FOO, "help") 
[1] "FOO expects two numbers, and it will add them together" 
attr(FOO, "comment") 
[1] "FOO performs simple addition" 

Y en el caso de comentario, use comment():

> comment(FOO) 
[1] "FOO performs simple addition" 

A largo plazo, escribir su propio paquete valdrá casi con toda seguridad la inversión de tiempo y tiempo, pero si por algún motivo no es práctico en el corto plazo, esta es otra opción.