[Rd] Help for methods

[Duncan Murdoch]

On 9/30/2006 1:17 AM, hadley wickham wrote:
>> 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.
> 
> I keep flipping back and forth on whether or not that's a problem.  I
> agree that it's not desirable, but may be an ok compromise in
> principle.  How does the S4 help search work?

See the .helpForCall function in utils.  It would recognize that the 
function was an S4 generic, and then work out the signature and look for 
matching help.  I think working out the signature in the case above 
would require it to call lm(...).  So there's a precedent for what I 
called a "huge mistake":  maybe it's not so huge...

Duncan Murdoch




> 
>> Do you have an actual suggestion for a change to the current behaviour?
> 
> One obvious heuristic (which I used with the hints function I wrote a
> while back) is to iterate through the classes of the first argument
> looking for functions (with documentation) of the form generic.class1,
> generic.class2 etc.
> 
> Obviously this will fail for functions that don't dispatch on the
> first method, but there probably aren't that many.
> 
> Hadley