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.

Urinate

I don't know whether this is also the case for reference classes, but S3 classes you would use \alias to address this same problem. – Reardon

That's not how usage blocks work unfortunately. Have you read the help about the built-in reference class documentation? – Artel

@hadley: I thought I had, but obviously I missed the \S4method item thing. to which documentation do you refer, that describes it? – Urinate

In "?ReferenceClasses" search for help. – Artel

yes, that I did, but there is no occurrence of the string S4method in that page. (I'm using R version 2.13.0 (2011-04-13)) – Urinate

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.

Urinate

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.

Scholarship

ok, but then more precisely: inside of the \usage section, I can add \S4method entries. for each S4method I document I need to add an \alias entry. the entries in the \alias do not need the list of parameters. – Urinate

If I understand you correct then you're right. For a method "foo", I tend to make an alias for "foo" and "foo.class-method" where foo is the name of the method and class is the name of the class. Again, I can't say that this is the Right Way, just how I have done them. – Scholarship

Jeoff, check my other answer, does it match what you are also doing? – Urinate

is there any way to split method definition in seperate files. Like initializr.R or populate.R? – Mole