[Rd] class extension and documentation

[Terry Therneau]

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
foo.default.
  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
code:
 
backsolve <- function(r, x, k=ncol(r), upper.tri=TRUE, ...) 
    UseMethod("backsolve")
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.