[BioC] Re: documenting S4 classes/accessors (fwd)

[Vincent Carey 525-2265]

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.

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