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 @slottag nelle prime descrizioni di roxygen. Un post della mailing list R-forge del 2008 sembra indicare che questo è morto, e non c'è supporto per @slotin roxygen:

È vero per roxygen2? Il post precedentemente citato suggerisce che un utente dovrebbe invece creare il proprio elenco dettagliato con markup LaTeX. Ad esempio una nuova classe S4 che estende la "character"classe 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 questo funziona, questo \describe, \iteml'approccio per documentare gli slot sembra in contrasto con il resto del roxygen (2), in quanto non ci sono @tag delimitato da e slot poteva andare senza documenti, senza obiezioni da parte roxygenize(). Inoltre non dice nulla su un modo coerente di documentare l'ereditarietà della classe che viene definita. Immagino che la dipendenza generalmente funzioni ancora bene (se un determinato slot richiede una classe non base da un altro pacchetto) usando il @importtag.

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 slot, come @param, che realizzerebbe la stessa cosa.

Sto prendendo in prestito / estendo questa domanda da un post che ho fatto alla roxygen2pagina di sviluppo su github .

Risposta aggiornata per Roxygen2 5.0.1, attuale alla 6.0.1

Per S4, la best practice ora sta documentando usando il @slottag:

#' 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

Su un sidenote, @exportClassè necessario solo in alcuni casi, il modo generale per esportare una funzione sta usando @exportora. 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, aggiornata 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 elenco all'interno dell'oggetto. Come hai sottolineato, questa sintassi è diversa dalle 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

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

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 hai usato @aliase @usage, semplicemente, fare affidamento su roxygen2 per fare la cosa giusta."