Come documentare correttamente gli slot di classe S4 utilizzando Roxygen2?

Question

Per documentare 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'ereditarietà sono il loro tipo di animale. Qual è la migliore pratica - attuale o pianificata - per documentare le classi S4 in roxygen2?

Due Diligence:

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

È vero per roxygen2? Il post citato in precedenza 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, sebbene questo funzioni, questo approccio \describe, \item per documentare gli slot sembra incoerente con il resto di roxygen (2), in quanto non ci sono tag delimitati da @ e gli slot potrebbero non essere documentati senza obiezioni da roxygenize(). Inoltre non dice nulla su un modo coerente per documentare l'ereditarietà della classe da definire. Immagino che la dipendenza in genere funzioni ancora bene (se uno slot particolare richiede una classe non base da un altro pacchetto) utilizzando il tag @import.

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

Sembra che al momento ci siano tre opzioni da considerare:

• A - Elenco dettagliato (come 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 è stato 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 comporterebbe la stessa cosa.

Prendo in prestito / estendo questa domanda da un post che ho pubblicato nella pagina di sviluppo del roxygen2 su github .

Answer 1

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 per S4.

In precedenza

Sembra che gli slot di classe S4 siano completamente supportati con 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 modo sicuro soluzioni alternative che utilizzavano @alias e @usage e affidarti semplicemente a roxygen2 per fare la cosa giusta."

Answer 2

Risposta aggiornata per Roxygen2 5.0.1, corrente a partire dalla 6.0.1

Per S4, la best practice ora è documentare utilizzando il tag @slot:

#' 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 è utilizzare @export ora. Inoltre non è necessario esportare una classe, a meno che non si desideri che altri pacchetti siano in grado di estendere la classe.

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

Risposta aggiornata per Roygen2 3.0.0, attuale alla 5.0.1.

Per S4, la migliore pratica è la documentazione nella forma:

#'  \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 fai notare, questa sintassi è diversa dalle altre righe e potremmo sperare in una soluzione più robusta in futuro che incorpori la conoscenza dell'ereditarietà, ma oggi questa non esiste.

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

Answer 3

La soluzione fornita da Full Decent va bene se cerchi di documentare gli slot nei file Rd stessi.Quando si utilizza roxygen2, è possibile utilizzare il tag @section per fare sostanzialmente 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