Re: [Rd] class extension and documentation

From: Terry Therneau <>
Date: Mon, 05 Dec 2011 14:34:30 -0600

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
  2. Warn that foo.default must now be exported. (I don't seem to need to export foo, exportMethods("foo") seems to be enough?)
  3. Warn that package creation will demand a manual page for foo and foo.default.
  4. Give hints on how to do b.
  5. 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 code:  

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. mailing list Received on Mon 05 Dec 2011 - 20:36:36 GMT

This quarter's messages: by month, or sorted: [ by date ] [ by thread ] [ by subject ] [ by author ]

All messages

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Tue 06 Dec 2011 - 01:00:15 GMT.

Mailing list information is available at Please read the posting guide before posting to the list.

list of date sections of archive