[BioC] Re: documenting S4 classes/accessors (fwd)
Robert Gentleman
rgentlem@jimmy.harvard.edu
Wed, 27 Mar 2002 07:40:34 -0500
On Wed, Mar 27, 2002 at 07:05:23AM -0500, Vincent Carey 525-2265 wrote:
> i am forwarding this exchange from core as it is potentially
> of general interest
>
> ---------- Forwarded message ----------
> Date: Wed, 27 Mar 2002 06:48:22 -0500 (EST)
> From: Vincent Carey 525-2265 <stvjc@channing.harvard.edu>
> To: Laurent Gautier <laurent@genome.cbs.dtu.dk>
> Cc: biocore@stat.math.ethz.ch
> Subject: Re: documenting S4 classes
>
> >
> > I am currently cleaning up/updating the documentation for the package 'affy'.
> > I am facing a rather annoying issue: the documentation of the methods.
> >
> > My first question is:
> > Are accessor methods really needed for every slot ? I understand that
> > for 'nested slots' they can provide a convenient way to access the data, but
> > when the slot is a known and documented object... isn't the '@' operator enough ?
>
> this is a somewhat obscure topic for me and i may not get
> it right, but RG will surely chime in if i get it wrong.
>
> use of the @-sign should be limited to 'internal' computations.
>
> when coding in R nothing is really 'private', but we want
> to simulate encapsulation as much as we can without changing
> the basic features of the language. we do not want user-level
> code to be reliant upon details of the internal representation
> of objects, and the @-sign is such a detail. we want to be
> able to modify the internal details without breaking
> user-level code. this can be accomplished if we use functions
> to broker access to the representation.
>
> example -- X is an exprSet X@exprs and X@se.exprs are current
> ways of referring to the expression data matrix and associated
> standard errors. Some wonderful thing may occur so that
> the expression data and standard errors are provided in a
> different sort of container that makes it easier to work with
> them -- say an eCont, which has slots exprs and se.exprs.
> so internally we need Z@eCont@exprs to get the exprs associated
> with Z in the new exprSet design.
>
> any user level code that refers to Z@exprs will fail unless
> we do some fancy footwork. but the accessor method could
> simply be recoded to get its argument's eCont@exprs data
> and user level code using exprs(Z) would work fine in both
> setups.
>
> no consolation at this point, but eventually accessors will
> be autogenerated.
I am a fan of accessors. Object oriented is one thing but usually
you get a lot from abstract data types (ADT's). When using @ there
is a presumption about the actual implementation of the object. This
is often not good style nor good code.
using getExprs(x) and setExprs(x) can be made to work when x has an
exprs slot, when that value is computed rather than stored etc.
I use the name of the slot (and hence get collisions). But the
get/set prefixes are fine. I would like
to see these autogenerated and I hope that things are going in that
direction.
>
> >
> > My second question is:
> > In the case my slots have names like 'sd' or 'history', I am really annoyed to
> > have accessor functions and document them by having '\alias{sd}' or
> > '\alias{history} in the '.Rd' file for the class since 'sd' and 'history' are
> > functions from 'base'. What should I do (in case the the answer to first
> > question was 'yes, we want accessor functions') ?
>
> i don't share your annoyance, but the problem of collisions
> among document references is real. sd-methods.Rd can be
> generated via promptMethods.
>
> we need some protracted thought about this -- many people are
> working on documentation concepts but at this time you just
> have to strike a balance between thoroughness and annoyance-reduction
>
> sorry!
>
> >
> >
> > ???
> >
> >
> >
> > L.
> >
> >
> >
> >
> > --------------------------------------------------------------
> > Laurent Gautier CBS, Building 208, DTU
> > PhD. Student D-2800 Lyngby,Denmark
> > tel: +45 45 25 24 85 http://www.cbs.dtu.dk/laurent
> > _______________________________________________
> > Biocore mailing list
> > Biocore@stat.math.ethz.ch
> > http://www.stat.math.ethz.ch/mailman/listinfo/biocore
> >
>
> _______________________________________________
> Biocore mailing list
> Biocore@stat.math.ethz.ch
> http://www.stat.math.ethz.ch/mailman/listinfo/biocore
>
> _______________________________________________
> Bioconductor mailing list
> Bioconductor@stat.math.ethz.ch
> http://www.stat.math.ethz.ch/mailman/listinfo/bioconductor
--
+---------------------------------------------------------------------------+
| Robert Gentleman phone : (617) 632-5250 |
| Associate Professor fax: (617) 632-2444 |
| Department of Biostatistics office: M1B28
| Harvard School of Public Health email: rgentlem@jimmy.dfci.harvard.edu |
+---------------------------------------------------------------------------+