[Rd] S4 accessors

[Ross Boylan]

I have a small S4 class for which I've written a page grouping many of
the accessors and replacement functions together.  I would be interested
in people comments on the approach I've taken.

The code has a couple of decisions for which I could imagine
alternatives.  First, even simple get/set operations on class elements
are wrapped in functions.  I suppose I could just use myinstance at slot to
do some of these operations, though that is considered bad style in more
traditional OO contexts.

Second, even though the functions are tied to the class, I've defined
them as free functions rather than methods.  I suppose I could create a
generic that would reject most arguments, and then make methods
appropriately.

For the documentation, I've created a single page that groups many of
the functions together.  This is a bit awkward, since the return values
are necessarily the same.  Things are worse for replacement functions;
as I understand it, they must use "value" for their final argument, but
the value has different meanings and types in different contexts.

Any suggestions or comments?

I've attached the .Rd file in case more specifics would help.
-- 
Ross Boylan                                      wk:  (415) 514-8146
185 Berry St #5700                               ross at biostat.ucsf.edu
Dept of Epidemiology and Biostatistics           fax: (415) 514-8150
University of California, San Francisco
San Francisco, CA 94107-1739                     hm:  (415) 550-1062
-------------- next part --------------
\name{runTime-accessors}
\alias{startTime}
\alias{endTime}
\alias{wallTime}
\alias{waitTime}
\alias{cpuTime}
\alias{mpirank}
\alias{mpirank<-}
\alias{remoteTime<-}
\title{ Accessors for runTime class}
\description{
  Set and get runTime related information.
}
\usage{
startTime(runTime)
endTime(runTime)
wallTime(runTime)
waitTime(runTime)
cpuTime(runTime)
mpirank(runTime)

mpirank(runTime) <- value
remoteTime(runTime) <- value
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{runTime}{a \code{runTime} object}
  \item{value}{for \code{mpirank}, the MPI rank of the associated job.
    For \code{remoteTime}, a vector of statistics from the remote processor: user
    cpu, system cpu, wall clock time for main job, wall clock time
    waiting for the root process.}
}
\details{
  All times are measured from start of job.  The sequence of events is
  that the job is created locally, started remotely, finished remotely,
  and completed locally.  Scheduling and transmission delays may occur.
  
  \item{startTime}{When the job was created, locally.}
  \item{endTime}{When job finished locally.}
  \item{wallTime}{How many seconds between local start and completion.}
  \item{cpuTime}{Remote cpu seconds used, both system and user.}
  \item{waitTime}{Remote seconds waiting for response from the local
    system after the remote computation finished.}
  \item{mpirank}{The rank of the execution unit that handled the remote computation.}
}
\value{
  Generally seconds, at a system-dependent resolution.
  \code{mpirank} is an integer.
  Replacement functions return the \code{runTime} object itself.
}
\author{Ross Boylan}
\note{Clients that use replacement functions should respect the semantics above.
}
\seealso{\code{\link{runTime-class}}}
\keyword{programming}
\keyword{environment}