¿cómo puedo documentar una clase de referencia R?

¿cómo documenta el uso de funciones miembro de una clase de referencia?¿cómo puedo documentar una clase de referencia R?

si escribo un archivo Rd con un bloque \usage, ¿cómo puedo evitar la WARNING

Functions/methods with usage in documentation object 'XmlDoc' but not in code: 
    $ new

yo esperaría que el bloque \usage para permitir a escribir cosas como:

obj <- ClassName$new(par1, par2, ...) 
obj$method1(oth1, ...)

y luego documentaría los parámetros en el bloque \arguments.

Si hago esto, se queja con R CMD check

Assignments in \usage in documentation object 'ClassName':

y no reconoce los métodos como objetos de código que necesito documento.

a partir de ahora, estoy escribiendo Rd archivos sin el bloque \usage y escribir el código anterior en el bloque \examples, pero luego no tienen lugar para documentar argumentos y de esta manera la check tiene muy poco que comprobar realmente. Como no estoy satisfecho con esto, ahora estoy preguntando a la comunidad sobre la práctica común actual.

Fuente

2011-07-20 mariotomo

No sé si este es también el caso para las clases de referencia, pero en las clases S3 se usaría '\ alias' para abordar este mismo problema. – Andrie

Así no es como funcionan los bloques de uso por desgracia. ¿Has leído la ayuda sobre la documentación incorporada de la clase de referencia? – hadley

@hadley: Pensé que sí, pero obviamente me perdí el elemento del artículo '\ S4method'. ¿A qué documentación se refiere, que lo describe? – mariotomo

No sé si es la manera correcta, pero lo que he hecho es tener una sección Métodos y luego poner la documentación del método en un interior describen.

Fuente

2011-07-20 15:37:08 geoffjentry

bien, pero luego más precisamente: dentro de la sección '\ usage', puedo agregar entradas' \ S4method'. para cada documento de S4method I, necesito agregar una entrada '\ alias'. las entradas en '\ alias' no necesitan la lista de parámetros. – mariotomo

Si entiendo tu correcto, entonces tienes razón. Para un método "foo", tiendo a hacer un alias para "foo" y "foo".class-method "donde foo es el nombre del método y clase es el nombre de la clase. De nuevo, no puedo decir que esta es la manera correcta, solo cómo lo hice. – geoffjentry

Jeoff, verifique mi otra respuesta, ¿Coincide con lo que también está haciendo? – mariotomo

si entiendo correctamente, los métodos de las clases de referencia son métodos S4, por lo que se aplica documenting S4 classes and methods.

para que esta respuesta sea un poco más independiente, esto es lo que estoy haciendo en el caso de la clase Logger en el paquete logging.oo.

este es el código que quería documentar, con algunos omissis [...].

Logger <- setRefClass("Logger", 
         fields=list(name = "character"), 
         methods=list(
         setLevel = function(newLevel) { [...] }, 
         getLevel = function() { [...] }, 
         addHandler = function(...) { [...] },

este es el contenido correspondiente del archivo .rd (s):

\alias{\S4method{new}{Logger}} 
\alias{\S4method{setLevel}{Logger}} 
\alias{\S4method{getLevel}{Logger}} 
\alias{\S4method{addHandler}{Logger}} 
[...] 
\usage{ 
\S4method{new}{Logger}(name) 
\S4method{setLevel}{Logger}(newLevel) 
\S4method{getLevel}{Logger}() 
\S4method{addHandler}{Logger}(...)

mientras que en el archivo NAMESPACE acabo de indicar que estoy exportando la clase Logger, no especifica su métodos: todos se exportan automáticamente.

Fuente

2011-07-22 07:13:55 mariotomo

¿cómo puedo documentar una clase de referencia R?

Respuesta

Cuestiones relacionadas