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.

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. — Andrie, Jul 20 '11 at 09:33
That's not how usage blocks work unfortunately. Have you read the help about the built-in reference class documentation? — hadley, Jul 21 '11 at 00:29
@hadley: I thought I had, but obviously I missed the `\S4method` item thing. to which documentation do you refer, that describes it? — mariotomo, Jul 21 '11 at 13:15
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)) — mariotomo, Jul 21 '11 at 19:08

score 5 · Answer 1 · answered Jul 20 '11 at 15:37

5

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.

answered Jul 20 '11 at 15:37

geoffjentry

4,674
3
31
37

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. – mariotomo Jul 21 '11 at 08:06
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. – geoffjentry Jul 23 '11 at 03:52
Jeoff, check my other answer, does it match what you are also doing? – mariotomo Jul 23 '11 at 19:41
is there any way to split method definition in seperate files. Like `initializr.R` or `populate.R`? – Matt Bannert Sep 27 '13 at 10:34

mariotomo · Accepted Answer · 2011-07-23T19:40:14.943

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.

how do I document an R Reference Class?

2 Answers2

Linked