[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   |
+---------------------------------------------------------------------------+