[Rd] S4 accessors

[Seth Falcon]

Ross Boylan <ross at biostat.ucsf.edu> writes:
> Did you want this offlist?  I'm happy keeping it on the list.

No, I accidentally responded privately and I believe I already resent
my reply to the list.  Sorry about that.  I've cc'd the list for this response.

>> If anyone else is going to extend your classes, then you are doing
>> them a disservice by not making these proper methods.  It means that
>> you can control what happens when they are called on a subclass. 

> My style has been to define a function, and then use setMethod if I want
> to redefine it for an extension.  That way the original version becomes
> the generic.
>
> So I don't see what I'm doing as being a barrier to adding methods.  Am
> I missing something?

You are not, but someone else might be: suppose you release your code
and I would like to extend it.  I am stuck until you decide to make
generics.

> Originally I tried defining the original using setMethod, but this
> generates a complaint about a missing function; that's one reason I fell
> into this style.

You have to create the generic first if it doesn't already exist:

   setGeneric("foo", function(x) standardGeneric("foo"))

>> For accessors, I like to document them in the methods section of the
>> class documentation.

> This is for accessors that really are methods, not my fake
> function-based accessors, right?

Which might be a further argument not to have the distinction in the
first place ;-)

To me, simple accessors are best documented with the class.  If I have
an instance, I will read help on it and find out what I can do with
it.  

> If you use foo as an accessor method, where do you define the associated
> function (i.e., \alias{foo})? I believe such a definition is expected by
> R CMD check and is desirable for users looking for help on foo (?foo)
> without paying attention to the fact it's a method.

Yes you need an alias for the _generic_ function.  You can either add
the alias to the class man page where one of its methods is documented
or you can have separate man pages for the generics.  This is
painful.  S4 documentation, in general, is rather difficult and IMO
this is in part a consequence of the more general (read more powerful)
generic function based system.

IOW, I think these are good questions.  They are ones that I struggle
with and do not know of any truly satisfying answers.

Best,

+ seth

-- 
Seth Falcon | Computational Biology | Fred Hutchinson Cancer Research Center
http://bioconductor.org