Re: [Rd] Help for methods

From: John Chambers <>
Date: Tue 19 Sep 2006 - 18:39:42 GMT

It's not likely that S3 methods will ever go away, at least in the sense that all the code using them would be rewritten. What we can work towards is to make more of the automated tools work for S3 methods as well as S4. This will usually involve package owners generating some information, though a good first approximation can often be done automatically.

I think the spirit of Hadley's request could be handled by introducing a declaration for S3 methods and by inserting S4-style alias{} lines into their documentation. For example, if a function, say setOldGeneric("summary"), similar to setOldClass, informed the system that "summary" was an S3 generic, then having an alias for "summary.lm-method" in the summary.lm.Rd file would allow a consistent set of documentation tools to work on those S3 methods and on S4 methods.

At the same time, it wouldn't hurt to have some more helpful hints to go from the top level of the documentation to the methods, for both S4 and S3 methods. Having metadata produced by setOldGeneric() would allow the system to offer a hint about method documentation. (And it would tell tools like "check" _not_ to require S4 method definitions for "summary".)

Duncan Murdoch wrote:
> On 9/19/2006 9:16 AM, hadley wickham wrote:

>>> In the alpha of 2.4.0, both suggestions above work, as do ?summary and
>>> ?summary(data.frame()).  ?summary(lm()) gives the same man page, rather
>>> than the summary.lm page (but the page does have a link to that page).
>> That's great.
>> The fact that summary includes a link to summary.lm is relevant for
>> this specific example, but not in general.
>> This is also related to my distaste for having multiple methods
>> documented in one function.  As a developer of R packages, I
>> understand why people do it (and do it myself), but as a user of help,
>> it makes the documentation harder to read.
>>> The problem with S3 methods is that it's pretty difficult for R to know
>>> that a particular object is an S3 generic.  The only sign is that it has
>>> a call to UseMethod() in it.  I think this is one of the motivations for S4.
>> Well, it is even more difficult for a human to know!

> Yes, I agree that the current help system doesn't work very well on S3
> methods. But I don't know how to fix it. I think the only way it could
> know what to do on a construction like

> ?summary(lm(...))

> would be to actually evaluate summary(lm(...)) (or maybe just lm(...)),
> and I think that would be a huge mistake in the user interface. Some
> functions have side effects, and you don't want to evaluate them unless
> the user asks you to. Asking for help on something should give you
> help, it shouldn't do the thing.

> Do you have an actual suggestion for a change to the current behaviour?

> I'd say the long term solution is to get rid of S3 dispatch, so this
> isn't an issue. There are improvements to S4 dispatch in 2.4.0, but I
> think there are very high barriers preventing people from using S4, so
> S3 will be around for a long time.

> Duncan Murdoch

> ______________________________________________
> mailing list

        [[alternative HTML version deleted]] mailing list Received on Wed Sep 20 04:43:46 2006

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.1.8, at Sat 30 Sep 2006 - 05:30:10 GMT.

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