R devel - Dec 2011 - class extension and documentation

I've added a "backsolve" method to the bdsmatrix library.
Per the Extending manual section 7.1 I've also added the following 3
lines along with my setMethod definitions for 2 classes.

backsolve <- function(r, ...) UseMethod("backsolve")
backsolve.default <- base:::backsolve
formals(backsolve.default) <- c(formals(backsolve.default), alist(...
= )) 

I've also added a backsolve-methods.Rd page, though since my arguments
are identical to the default it doesn't say much.  And, after a test
failed, added the new backsolve.default routine to my export list.

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?

Perhaps do setMethod("backsolve", signature(r="ALL"),
                           base:::backsolve(r, ...))
instead?

Terry Therneau

On 05/12/2011 12:11 PM, Terry Therneau wrote:
> I've added a "backsolve" method to the bdsmatrix library.
> Per the Extending manual section 7.1 I've also added the following 3
> lines along with my setMethod definitions for 2 classes.
>
> backsolve<- function(r, ...) UseMethod("backsolve")
> backsolve.default<- base:::backsolve
> formals(backsolve.default)<- c(formals(backsolve.default), alist(...
> = ))
>
> I've also added a backsolve-methods.Rd page, though since my arguments
> are identical to the default it doesn't say much.  And, after a test
> failed, added the new backsolve.default routine to my export list.
>
> 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.

Duncan Murdoch

> Perhaps do setMethod("backsolve", signature(r="ALL"),
>                             base:::backsolve(r, ...))
> instead?
>
> Terry Therneau
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

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.