How to document S4 methods correctly with roxygen2

Question

I have seen some discussions in SO and elsewhere regarding how this should be or will be done in future versions of Roxygen2. However, I am stuck. How should I document the general S4 movie, as well as its methods, using Roxygen2? A working example for new generic / methods, as well as an example of extending the base S4 generic value will be incredibly useful. I don’t want to do separate (mostly) redundant documentation for each S4 method of the same generic.

Due dilligence: I found a useful example for the "extract" method. However, in my opinion, it is obsolete and incomplete. It uses the @slot tag in the documentation for a class that is not supported (no longer supported). It shows only an extension of the main S4 method "[", and not a complete Roxygen example, including the S4 generic documentation.

How to properly document S4 "[" and "[<-" methods using roxygen?

If I fully document the new S4 generic file with the header, description @param @return @name @aliases @docType @rdname , and then document the S4 method only with the corresponding @name @aliases @docType @rdname , I get the following R CMD check warning:

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

At first it looked as if none of my S4 methods described in this way with roxygen2 actually worked. However, so far I have noticed that my extensions to the main "show" method do not have a related error, although they have been documented in exactly the same way as the others. The following is an example of the complete roxygen documentation included above one of the show methods that did NOT generate an error with the missing documentation:

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

So I'm at a loss. As you can see, I have included the convention for aliases for S4 methods described in the S4 documentation section of the R package guide , namely: methods must have an alias with the following name (without a space):

 generic,signature_list-method. 

Somehow this is not fully understood by the R CMD check .

Finally, after creating the documentation, using:

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

and creating the package, I get valid documentation. Any headings from the method’s special documentation end in the Description field, which is rather awkward. Therefore, roxygen2 has obviously done something with each method documentation and is on the right track. However, this is not enough to avoid a large and alarming warning from

 > R CMD check mypkgname 

I looked at the Rd files, but I know even less about them to quickly understand what the problem is, and I still want to know the solution of roxygen2 so that I do not have to manipulate the Rd files immediately after each revision of the documentation.

So this is a question with a few questions:

• What is the current recommended approach for both S4 documentation and S4 using roxygen2?

• Is there a good example somewhere that shows complete information?

• What could be the reason and solution for warning that documentation for most S4 methods is missing (even if methods with "missing" documentation actually had their document processed by roxygen2, and the resulting Rd files are at least enough to work in the package after R CMD build mypkgname )?

Answer 1

Official support described in devtools doc

http://r-pkgs.had.co.nz/man.html#man-classes (scroll down to subsection S4 ).

The current short example from this page is reproduced as follows (for convenience):

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

The above link very clearly explains support for S3, S4 and RC via roxygen / devtools. An explanation there should be considered in order to replace the older answer below, which works at the moment, but is less clear and more complicated.

Old answer

Here is an example that should work for most S4 methods.

To document S4 generic files in most of my common headers, I find the following three lines:

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

Where helloworld-methods is replaced with the_name_of_your_generic-methods . This will be the name of the Rd file containing the documentation for the generic and all of its methods. This naming convention is not required, but is general and useful. The @export tag @export needed now that the namespace is required for your package, and you want this method to be available to users of your package, and not just other methods / functions in your package.

To document the methods, I found that only two lines are needed containing the tags @rdname and @aliases . The @rdname operator must exactly match the one specified for the general. The @aliases tag must adhere to the naming convention described in the official S4 documentation section Writing R Extensions .

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

There should be no spaces after commas in the @aliases name. I do not know the exact rules associated with adding ,ANY to the end of the signature list. It seems that the pattern is that the number of elements in all @aliases signature @aliases should match the number of elements in the longest signature signal among the methods. In the example below, one of the methods is defined using a two-element signature, so the R CMD check not satisfied with the documentation, unless ,ANY was added to the aliases tag of other methods, even if their signature definition only has one element.

The following is a complete example. I built this and it works without warning at the documentation level from R CMD check testpkg , using the fork bug fix of the very recent version of roxygen2 (which I provided) . To quickly install this fork on your system, use library("devtools"); install_github("roxygen", "joey711") library("devtools"); install_github("roxygen", "joey711") . The latest version of roxygen2 will not work at this moment due to a quote error (described in a separate answer), but I expect it to be turned on very soon, and my plug will not be needed. To view this example in the context of the rest of the package and view the resulting documentation (Rd) files, I made it available as a trivial test package for github called 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) }) 

This example assumes that you do not need separate documentation for specific methods because your methods did not deviate much from the behavior you would expect based on a common document. Roxygen2 has tools to handle this alternative case using the @usage tag, but details will be better handled by a separate SO question.

Thus, most of your documentation effort goes into the roxygen heading over the general definition. This has some basis in the code, since the general should include all the specific arguments that appear in any of the subsequently defined methods. Note that arguments that are processed as part of ... in the argument list are not included and should not be documented, but ... itself should be documented above the general (see. Full example below).

For more information on the basics of documenting features, there is a wiki , an old rogen vignette , and the roxygen2 development site on github . There is also an SO R documentation issue with Roxygen in general.

Answer 2

I found that the answer to part (3) is the documentation on S4 methods, which is not missing, due to the fact that quotation marks are added erroneously around \ alias tags when using the S4 naming convention; most likely an error that occurs as a result of processing the text of an alias that contains a comma as part of its name. This still applies to the latest version of roxygen2 at the time of this publication. I just posted a more detailed error description with a reproducible example on the roxygen2 github page:

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

In short

 #' @aliases show,helloworld-method 

becomes

 \alias{"show,helloworld-method"} 

in the resulting Rd file. Removing citations removes the R CMD check warning, and the documentation assembly also works in both cases.

I think that parts (1) and (2) of this question (best practices, good examples) are still open.