how do I document an R Reference Class?

Question

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.

Answer 1

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.

Answer 2

I don't know if it's the Right Way, but what I've done is to have a Methods section and then put the method documentation in an interior describe.