it-swarm.it

Come documentare correttamente gli slot di classe S4 usando Roxygen2?

Per documentare le classi con roxygen (2), specificare un titolo e una descrizione/dettagli sembra essere lo stesso di funzioni, metodi, dati, ecc. Tuttavia, gli slot e l'eredità sono il loro stesso tipo di animale. Qual è la migliore pratica - attuale o pianificata - per documentare le classi S4 in roxygen2?

Diligenza dovuta:

Ho trovato la menzione di un tag _@slot_ nelle prime descrizioni di roxygen. n post della mailing list R-forge del 2008 sembra indicare che questo è morto, e non c'è supporto per _@slot_ in roxygen:

È vero per roxygen2? Il post precedentemente citato suggerisce che un utente dovrebbe invece creare il proprio elenco dettagliato con markup LaTeX. Per esempio. una nuova classe S4 che estende la classe _"character"_ sarebbe codificata e documentata in questo modo:

_#' The title for my S4 class that extends \code{"character"} class.
#'
#' Some details about this class and my plans for it in the body.
#'
#' \describe{
#'    \item{myslot1}{A logical keeping track of something.}
#'
#'    \item{myslot2}{An integer specifying something else.}
#' 
#'    \item{myslot3}{A data.frame holding some data.}
#'  }
#' @name mynewclass-class
#' @rdname mynewclass-class
#' @exportClass mynewclass
setClass("mynewclass",
    representation(myslot1="logical",
        myslot2="integer",
        myslot3="data.frame"),
    contains = "character"
)
_

Tuttavia, anche se funziona, questo approccio _\describe_, _\item_ per documentare gli slot sembra incompatibile con il resto di roxygen (2), in quanto non ci sono tag e slot delimitati _@_ andare senza documenti senza obiezioni da parte di roxygenize(). Inoltre non dice nulla su un modo coerente di documentare l'ereditarietà della classe definita. Immagino che la dipendenza generalmente funzioni ancora bene (se un determinato slot richiede una classe non base da un altro pacchetto) usando il tag _@import_.

Quindi, per riassumere, qual è l'attuale best practice per gli slot roxygen (2)?

Sembra che ci siano tre opzioni da considerare al momento:

  • A - Elenco dettagliato (come nell'esempio sopra).
  • B - _@slot_ ... ma con tag/implementazione extra mi sono perso. Non sono riuscito a far funzionare @slot con roxygen/roxygen2 nelle versioni in cui era incluso in sostituzione dell'elenco dettagliato nell'esempio sopra. Ancora una volta, l'esempio sopra funziona con roxygen (2).
  • C - Qualche tag alternativo per specificare gli slot, come _@param_, che realizzerebbe la stessa cosa.

Sto prendendo in prestito/estendo questa domanda da un post che ho scritto alla pagina di sviluppo _roxygen2_ su github .

301
Paul McMurdie

roxygen2 v4.1 + e l'ultimo documento di Hadley per fare questo:

http://r-pkgs.had.co.nz/man.html#man-classes

Non l'ho ancora provato per RC, ma ora funziona con S4.

In precedenza

Sembra che gli slot di classe S4 siano completamente supportati in Roxygen2 versione 3.0+:

http://blog.rstudio.org/2013/12/09/roxygen2-3-0-0/

"documenta le tue classi S4, i metodi S4 e le classi RC con roxygen2: puoi rimuovere in sicurezza le soluzioni alternative che hanno utilizzato @alias e @usage e fai semplicemente affidamento su roxygen2 per fare la cosa giusta. "

14
Paul McMurdie

Risposta aggiornata per Roxygen2 5.0.1, attuale a 6.0.1

Per S4, la best practice ora sta documentando usando @slot tag:

#' The title for my S4 class that extends \code{"character"} class.
#'
#' Some details about this class and my plans for it in the body.
#'
#' @slot myslot1 A logical keeping track of something.
#' @slot myslot2 An integer specifying something else.
#' @slot myslot3 A data.frame holding some data.
#'
#' @name mynewclass-class
#' @rdname mynewclass-class
#' @export

In una nota a margine, @exportClass è necessario solo in alcuni casi, il modo generale per esportare una funzione sta usando @export adesso. Inoltre, non è necessario esportare una classe, a meno che non si desideri che altri pacchetti siano in grado di estenderla.

Vedi anche http://r-pkgs.had.co.nz/namespace.html#exports

Risposta aggiornata per Roygen2 3.0.0, attuale a 5.0.1.

Per S4, la migliore pratica è la documentazione nel modulo:

#'  \section{Slots}{
#'    \describe{
#'      \item{\code{a}:}{Object of class \code{"numeric"}.}
#'      \item{\code{b}:}{Object of class \code{"character"}.}
#'    }
#'  }

Ciò è coerente con la rappresentazione interna degli slot come un elenco all'interno dell'oggetto. Come hai sottolineato, questa sintassi è diversa rispetto alle altre linee e in futuro potremmo sperare in una soluzione più solida che incorpori la conoscenza dell'eredità, ma oggi non esiste.

Come sottolineato da @Brian Diggs, questa funzione è stata inserita in 3.0.0, ulteriore discussione su https://github.com/klutometis/roxygen/pull/85

28

La soluzione fornita da Full Decent è OK se si va per documentare gli slot nei file Rd stessi. Quando si usa roxygen2, puoi utilizzare il tag @section per fare praticamente lo stesso con \describe. Un esempio:

#' The EXAMPLE class
#'
#' This class contains an example. This line goes into the description
#'
#' This line and the next ones go into the details.
#' This line thus appears in the details as well.
#'
#'@section Slots: 
#'  \describe{
#'    \item{\code{slot1}:}{Matrix of class \code{"numeric"}, containing data from slot1}
#'    \item{\code{slot2}:}{Object of class \code{"character"}, containing data that needs to go in slot2.}
#'  }
#'
#' @note You can still add notes
#' @name EXAMPLE 
#' @rdname EXAMPLE
#' @aliases EXAMPLE-class
#' @exportClass EXAMPLE
#' @author Joris Meys
18
Joris Meys