[Roxygen-devel] What's missing in S4?

[Bernd Bischl]

Hi,
to add a few questions / comments to S4 support in roxygen:

1) If a slot of a S4 class has type "ANY" roxygen tries to code/link it, 
which then does not pass the check because of the link. This should be 
easily fixable by adding a case in
Rdapi.R, slotTag ?

2) I usually use the approach (also discussed here on the list) to 
document multiple methods and the generic together in the same Rd file 
by using @rdname.
I have no idea how to generate more than 1 usage statement. (Lets say 
you have 2 methods and they some have different extra arguments not in 
the signature)
If I put @usage foo(x,y)  and @usage foo(x,z)  before the setMethods, 
roxygen concatenates like this in the RD file
Usage:
foo(x,y)foo(x,z)

3) Lets say you have a generic "foo" and a corresponding method which 
are both not exported and the method dispatches on class "A" by its 
first argument. Now roxygen adds "foo" to the "Methods" section of class 
"A" (and also tries to link it).
I think its also added to the index set of the package.

Two things that I currently do manually but that roxygen should be able 
to do autmatically IMHO:

4) Document all subclasses (in my package) of a class in its Rd file. I 
am used to this from javadoc and it makes navigation much simpler in 
some cases.

5) Document the argument types in S4 methods. I usually write something 
like this:
#' @param a [\code{\linkS4class{ClassA}}] \cr
#'   Object of ClassA.
#' @param doit [\code{logical(1)}] \cr
#'   Do something?
I know getting the length information (1)  into the second parameter is 
probably hard, but it would be great if roxygen would at least doument 
that its a logical, which is easily accessible from the signature. I did 
some tracing and the information seems to be already collected, if I 
look at partitum$S4formals$signature


I have begun to extract all my roxygen problems with S4 (above and a few 
more) into a self-contained R example file.  I could post this.

Regards,

Bernd