Come documentare correttamente i metodi S4 usando ROXYGEN2

Question

Ho visto alcune discussioni in SO e in altri luoghi su come dovrebbe essere o fare nelle versioni future di Roxygen2. Tuttavia, sono bloccato. Come dovrei documentare un generico S4 e i suoi metodi, usando Roxygen2? Un esempio funzionante per un nuovo generico/metodi di zecca, nonché un esempio per estendere la base S4 generica sarebbe incredibilmente utile. Non voglio dover realizzare documentazione separata (principalmente) ridondante per ciascun metodo S4 dello stesso generico.

Due Dilligence: ho rintracciato un utile esempio per il metodo "estratto". Tuttavia, sembra essere obsoleto e incompleto per la mia domanda. Utilizza il tag @slot nella documentazione della classe, che non è (non più?) Supportato. Mostra solo un'estensione di un metodo Core S4 [", piuttosto che un esempio di roxygen completo che include la documentazione del generico S4.

Come documentare correttamente S4 [" e “[<-” Metodi usando Roxygen?

Se documentare completamente un nuovo s4 generico con titolo, descrizione @param @return @name @aliases @docType @rdname, e quindi documenta il metodo S4 con solo il corrispondente @name @aliases @docType @rdname, Ottengo quanto segue R CMD check avvertimento:

* checking for missing documentation entries ... WARNING
Undocumented S4 methods:
<< long list of apparently undocumented methods. E.g. generic 'plot' and siglist 'myClass1,ANY' >>
All user-level objects in a package (including S4 classes and methods)
should have documentation entries.

All'inizio sembrava che nessuno dei miei metodi S4 documentati in questo modo con Roxygen2 avesse effettivamente funzionato. Tuttavia, finora, ho notato che le mie estensioni del metodo principale "mostrano" non hanno un errore associato, anche se sono state documentate esattamente allo stesso modo del resto. Ecco un esempio della documentazione completa di Roxygen che ho incluso sopra uno dei metodi Show, che non ha generato l'errore di documentazione mancante:

#' @name show
#' @aliases show,myClass2-method
#' @docType methods
#' @rdname show-methods

Quindi, sono in perdita. Come puoi vedere, ho incluso la convenzione per gli alias per i metodi S4 descritti in La sezione documentazione S4 del manuale del pacchetto R, vale a dire che i metodi dovrebbero avere un alias con il seguente nome (senza spazio):

generic,signature_list-method.

In qualche modo, questo non viene completamente compreso da R CMD check.

Infine, dopo aver costruito la documentazione usando:

library("devtools")
library("roxygen2")
document("mypkgname")
check_doc("mypkgname")

E creando il pacchetto, ottengo la documentazione di funzionamento. Tutti i titoli di una documentazione di un metodo specifico finiscono nel campo "Descrizione", piuttosto goffamente. Quindi Roxygen2 ovviamente ha fatto qualcosa con la documentazione di ogni metodo ed è sulla buona strada. Tuttavia, non è sufficiente evitare un avvertimento grande e preoccupante

> R CMD check mypkgname

Ho guardato i file RD, ma ne so ancora meno per vedere rapidamente qual è il problema, e comunque voglio conoscere la soluzione ROXYGEN2 in modo da non dover manipolare i file RD direttamente dopo ogni revisione della documentazione.

Quindi questa è una domanda multipart:

1. Qual è l'attuale approccio raccomandato per la documentazione del metodo generico e S4 S4 con ROXYGEN2?

2. C'è un buon esempio disponibile da qualche parte che mostra i dettagli completi?

3. Quale potrebbe essere la causa e la soluzione, all'avvertimento che manca la documentazione per la maggior parte dei metodi S4 (anche se i metodi con la documentazione "mancante" hanno effettivamente analizzato il loro DOC da Roxygen2 e i file RD risultanti sono almeno abbastanza buoni per funzionare nella confezione dopo R CMD build mypkgname) ?

Answer 1

Supporto ufficiale, spiegato in DevTools Doc

http://r-pkgs.had.co.nz/man.html#man-lasses(Scorri verso il basso verso il S4 sottosezione).

L'attuale breve esempio di quella pagina è riprodotto nel seguente (per comodità):

#' An S4 class to represent a bank account.
#'
#' @slot balance A length-one numeric vector
Account <- setClass("Account",
  slots = list(balance = "numeric")
)

Il link sopra spiega molto chiaramente il supporto S3, S4 e RC tramite Roxygen/DevTools. La spiegazione dovrebbe essere considerata per sostituire la risposta più vecchia di seguito, che funziona per ora, ma è meno chiara e più complicata.

La vecchia risposta

Ecco un esempio che dovrebbe funzionare per la maggior parte dei metodi S4.

Per documentare i generici S4, trovo le seguenti tre righe necessarie nella maggior parte delle mie intestazioni generiche:

#' @export
#' @docType methods
#' @rdname helloworld-methods

Dove helloworld-methods è sostituito con the_name_of_your_generic-methods. Questo sarà il nome del file RD che contiene la documentazione per il generico e tutti i suoi metodi. Questa convenzione di denominazione non è richiesta, ma comune e utile. Il @export Il tag è necessario ora che uno spazio dei nomi sia richiesto per il tuo pacchetto e desideri che questo metodo sia disponibile per gli utenti del pacchetto, non solo altri metodi/funzioni nel pacchetto.

Per la documentazione dei metodi, trovo che siano necessarie solo 2 righe, fornendo il @rdname e @aliases etichetta. Il @rdname L'istruzione dovrebbe corrispondere esattamente a quella per il generico. Il @aliases Il tag deve aderire a una convenzione di denominazione descritta nella sezione Documentazione ufficiale di S4 di Scrivere estensioni R..

#' @rdname helloworld-methods
#' @aliases helloworld,character,ANY-method

Non dovrebbero esserci spazi dopo le virgole nel @aliases nome. Non conosco le regole esatte che circondano quando aggiungere ,ANY alla fine dell'elenco delle firme. Il modello sembra essere il numero di elementi in tutto @aliases Gli elenchi di firma devono abbinare il numero di elementi nel vettore di firma più lungo tra i metodi. Nell'esempio seguente, uno dei metodi è definito con firma a 2 elementi e così R CMD check non era soddisfatto della documentazione se non ,ANY è stato aggiunto al tag alias degli altri metodi, anche se la loro definizione di firma ha solo un elemento.

Segue un esempio completo. Ho costruito questo e funziona senza avvertimenti a livello di documentazione da R CMD check testpkg, usare un FORCHIO FOSTATO BUG di una versione sviluppata molto recente di Roxygen2 (che ho reso disponibile). Per una rapida installazione di questa forchetta sul sistema, usa library("devtools"); install_github("roxygen", "joey711"). La versione più recente di Roxygen2 non funzionerà in questo momento a causa di un errore di citazione (descritto in una risposta separata), ma mi aspetto che questo sarà incorporato molto presto e la mia forcella non sarà necessaria. Per esaminare questo esempio nel contesto del resto di un pacchetto e vedere i file di documentazione risultante (RD), l'ho reso disponibile come pacchetto di test banali su GitHub chiamato testpkg.

##############################################################
#' The title, in this case: Helloworld-ify the argument.
#'
#' Some additional details about this S4 generic and its methods.
#' The extra blank line between this section and the title is
#' critical for roxygen2 to differentiate the title from the
#' description section.
#'
#' @param x Description of \code{x}. The main argument in this
#'  example. Most often has such and such properties.
#'
#' @param y Description of \code{y}. An argument that is rarely
#'  used by \code{"helloworld"} methods. 
#'
#' @param ... Additional argument list that might not ever
#'  be used.
#'
#' @return A helloworld-ified argument. Oh, you'll see.
#' 
#' @seealso \code{\link{print}} and \code{\link{cat}}
#' 
#' @export
#' @docType methods
#' @rdname helloworld-methods
#'
#' @examples
#' helloworld("thisismystring")
#' helloworld(char2helloworld("thisismystring"))
#' helloworld(matrix(0,3,3))
#' helloworld(list(0,0,0))
#' helloworld(integer(0))
setGeneric("helloworld", function(x, y, ...){
    cat("Hello World!")
    cat("\n")
    standardGeneric("helloworld")
})

#' @rdname helloworld-methods
#' @aliases helloworld,ANY,ANY-method
setMethod("helloworld", "ANY", function(x, y, ...){
    cat(class(x))
})

#' @rdname helloworld-methods
#' @aliases helloworld,character,ANY-method
setMethod("helloworld", "character", function(x){
    show(x)
})

#' @rdname helloworld-methods
#' @aliases helloworld,character,character-method
setMethod("helloworld", c("character", "character"), function(x, y){
    show(x)
})

Questo esempio presuppone che non sia necessaria una documentazione specifica per il metodo separata perché i tuoi metodi non si sono impegnati selvaggiamente dal comportamento che ci si aspetterebbe in base al documento generico. Ci sono mezzi in Roxygen2 per gestire quel caso alternativo usando il @usage Tag, ma i dettagli sarebbero meglio gestiti da una domanda SO separata.

Quindi la maggior parte del tuo sforzo di documentazione va nell'intestazione di Roxygen sopra la definizione generica. Ciò ha alcune basi nel codice, poiché il generico dovrebbe includere tutti gli argomenti specifici che compaiono in uno qualsiasi dei metodi successivamente definiti. Si noti che gli argomenti che vengono gestiti come parte del ... Nell'elenco degli argomenti non sono inclusi e non dovrebbero essere documentati specificamente, ma il ... stesso dovrebbe essere documentato sopra anche il generico (vedere l'intero esempio di seguito).

Per ulteriori dettagli sulle basi delle funzioni di documentazione, esiste un Wiki in corso, il Vecchia vignetta di Roxygen, così come il Sito di sviluppo ROXYGEN2 su GitHub. C'è anche un Quindi domande sulla documentazione R con Roxygen in generale.

Answer 2

Ho rintracciato che la risposta alla parte (3)-la documentazione non così mancata dei metodi S4-è dovuta ai marchi di virgoletta aggiunti erroneamente attorno ai tag alias quando viene utilizzata la convenzione di denominazione S4; Molto probabilmente un bug derivante dalla gestione del testo di un alias che contiene una virgola come parte del suo nome. Questo è ancora vero per l'ultima versione di Roxygen2 al momento di questo post. Ho appena pubblicato una descrizione più approfondita del bug con un esempio riproducibile sulla pagina Roxygen2 GitHub:

https://github.com/klutometis/roxygen/issues/40

Brevemente,

#' @aliases show,helloworld-method

diventa

\alias{"show,helloworld-method"}

Nel file RD risultante. La rimozione delle citazioni rimuove il R CMD check Avvertenza e la documentazione si accumula ed è funzionale in entrambi i casi.

Penso che parti (1) e (2) di questa domanda (migliori pratiche; buoni esempi) si aprano.