[Rd] Help for methods

[Duncan Murdoch]

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