how do I document an R Reference Class?

documentation, r, rd, reference-class

Solution

if I understood correctly, Reference Classes methods are S4 methods, so documenting S4 classes and methods applies.

to make this answer a bit more self contained, here is what I am doing in the case of the `Logger` class in the `logging.oo` package.

this is the code I wanted to document, with some omissis [...].

Logger <- setRefClass("Logger",
                      fields=list(name = "character"),
                      methods=list(
                        setLevel = function(newLevel) { [...] },
                        getLevel = function() { [...] },
                        addHandler = function(...) { [...] },

this is the corresponding content of the .Rd file(s):

\alias{\S4method{new}{Logger}}
\alias{\S4method{setLevel}{Logger}}
\alias{\S4method{getLevel}{Logger}}
\alias{\S4method{addHandler}{Logger}}
[...]
\usage{
\S4method{new}{Logger}(name)
\S4method{setLevel}{Logger}(newLevel)
\S4method{getLevel}{Logger}()
\S4method{addHandler}{Logger}(...)

while in the NAMESPACE file I just indicate I'm exporting the Logger class, I don't specify its methods: all are automatically exported.

Problem

how do I document the use of member functions of a reference class? if I write a `Rd` file with a `\usage` block, how do I avoid the `WARNING` ``` Functions/methods with usage in documentation object 'XmlDoc' but not in code: $ new ``` I'd expect the `\usage` block to allow me write things like: ``` obj <- ClassName$new(par1, par2, ...) obj$method1(oth1, ...) ``` and then I'd document the parameters in the `\arguments` block. If I do this, `R CMD check` complains with ``` Assignments in \usage in documentation object 'ClassName': ``` and does not recognize the methods as code objects I need document. as of now, I am writing `Rd` files without the `\usage` block and writing the above code in the `\examples` block, but then I have no place to document arguments and this way the `check` has very little to check actually. Since I'm not satisfied with this, I'm now asking the community about the current common practice.

Original source