[Rd] class extension and documentation

Terry Therneau therneau at mayo.edu
Mon Dec 5 21:34:30 CET 2011

Duncan's reply to my query

> Now R CMD check claims that I need Rd pages for backsolve and
> backsolve.default.  I don't think I should rewrite those.
>     How do I sidestep this  and/or
>     what other manuals should I read?

Even though your change is subtle, I'd say it's still a change 
(backsolve is now a generic, not a simple closure; it now has a 
different argument list), so I'd like to see a new man page added.  It 
would be quite reasonable to list the new interface and then refer to 
base::backsolve for the details of what the default method does.


Fair enough.  Let's push this a little harder.

 1. Additions to the manual, section 7.1
  a. Warn that foo.default must now be exported.  (I don't seem to
need to export foo, exportMethods("foo") seems to be enough?)
  b. Warn that package creation will demand a manual page for foo and
  c. Give hints on how to do b.

 2. More information in the setMethod page on the fragility of "just add 
one to make a generic".  I can't make this work if any of the arguments
have defaults.


Trying to impliment this idea is turning into a quagmire.  Here is my current
backsolve <- function(r, x, k=ncol(r), upper.tri=TRUE, ...) 
backsolve.default <- base:::backsolve
formals(backsolve.default) <- c(formals(backsolve.default), alist(... = )) 

setMethod("backsolve", signature(r="gchol", x="ANY", k="ANY", upper.tri="ANY"),
      function(r, x, k=ncol(r), upper.tri=TRUE, ...) {
          if (any(diag(r) < 0))
              stop("Argument has a negative diagonal, cannot backsolve")

          if (!is.numeric(x)) stop("Invalid data type for x")
          x <- as.matrix(x)

 First, if I was going to have a new backsolve manual page, it should
mention the arguments.  This meant adding x, k, and upper.tri to the
generic above.  And they needed defaults to make the Rd page be both
correct and pass muster.

 Now, however the default method doesn't work.  backsolve of an
ordinary matrix leads to
    Error in k != floor(k) : 'k' is missing
    Calls: backsolve -> backsolve -> .local
What's the trick?

 The gchol method for backsove was documented via promptMethod. 
How do I refer to this object in a \link from backsolve?  

  Accessing that documentation is certainly a challenge.  I doublt I'll ever
find a user to guess or remember
   methods?backsolve("gchol", "ANY", "ANY", "ANY")

Terry T.

More information about the R-devel mailing list