Jeff, this sounds like a standardized data format, not a function. You are
basically telling the user how to put their own data into the correct format.
You are not giving them any data (at least not with this file), and you are not
giving them a function because there is no function here to do the same thing
over and over with different data.
If this sounds right, I think the answer is you have to write your own custom
Rd file that as far as I know is not really documented per se. However, I have
done this exact thing, so I'm appending an example below (from package
ChemoSpec). See if this makes sense. Bryan
\name{Spectra}
\Rdversion{1.1}
\title{
Spectra Objects
}
\alias{Spectra}
\description{
In \code{ChemoSpec}, spectral data sets are stored in an S3 class called
\code{Spectra}, which contains a variety of information in addition to the
spectra themselves. \code{Spectra} objects are created by
\code{\link{getManyCsv}} or similar functions (no others currently exist).
}
\section{Structure}{
The structure of a \code{Spectra} object is a list of 7 elements and an
attribute as follows:
\tabular{lll}{
\emph{element} \tab \emph{type} \tab \emph{description}\cr
$freq \tab num \tab A common frequency (or wavelength) axis for all the
spectra.\cr
$data \tab num \tab The intensities for the spectra. A matrix of dimension \cr
\tab \tab no. samples x no. frequency points.\cr
$names \tab chr \tab The sample names for the spectra; length must be no.
samples.\cr
$groups \tab Factor \tab The group classification of the samples; length must
be no. samples.\cr
$colors \tab chr \tab The colors for each sample; length must be no. samples.
\cr
\tab \tab Groups and colors correspond.\cr
$sym \tab integer \tab As for \code{colors}, but symbols for plotting (if b/w
is desired).\cr
$alt.sym \tab chr \tab Lower-case letters as alternate symbols for plotting.\cr
$unit \tab chr \tab Two entries, the first giving the x axis unit, the second
the y axis unit.\cr
$desc \tab chr \tab A character string describing the data set. This appears
on plots and therefore \cr
\tab \tab should probably be kept to 40 characters or less.\cr
- attr \tab chr "Spectra" \tab The S3 class designation.\cr
}
}
\seealso{
\code{\link{sumSpectra}} to summarize a \code{"Spectra"} object.
\code{\link{sumGroups}} to summarize group membership of a \code{"Spectra"}
object.
\code{\link{chkSpectra}} to verify the integrity of a \code{"Spectra"} object.
\code{\link{colorSymbol}} for a discussion of color options.
}
\references{
\url{http://academic.depauw.edu/~hanson/ChemoSpec/ChemoSpec.html}
}
\author{
Bryan A. Hanson, DePauw University. \email{han...@depauw.edu}
}
\keyword{ classes }
On Jan 6, 2012, at 2:48 PM, Jeff Hamann wrote:
> I know I should provide a better answer, but I think it's really for a
> function.
>
> For this package, we simply pass a list object about, but have to obfuscate
> it using a domain familiar nomenclature for the users.
>
> So, not a data set, but a function. I think.
>
> Here's the file in it's entirety:
>
>
> %% $Id $
>
> \name{sample.data}
> \alias{sample.data}
>
> \title{CONIFERS forest growth model sample data}
>
> \description{ A list object of type \code{sample.data} stores all of
> the basic information about a \code{\link{data.frame}} object
> representing a sample of plants.}
>
> \usage{
> x <- list( plots=data.frame(), plants=data.frame(), age=0, x0=0.0,
> n.years.projected=0 )
> class(x) <- "sample.data"
> }
>
> \details{
> To create the basic data type used in rconifers, you create a
> list object with the following elements (order is not
> important):
> \describe{
> \item{plots}{is a \link{data.frame} with the the same elements as
> \code{\link{plots.swo}}.}
> \item{plants}{is a \link{data.frame} with the the same elements as
> \code{\link{plants.swo}}.}
> \item{age}{is an integer value that represents the age of the plants,
> in years.}
> \item{x0}{is the $x_{0}$ coefficient for the Hann and Wang (1990) mortality
> model.}
> \item{n.years.projected}{is the number of years that $x$ has been
> projected forward in time.}
> }
> }
>
> \references{
>
> Ritchie, M.W. 2008. User's Guide and Help System for CONIFERS: A Simulator
> for Young Conifer Plantations Version
> 4.10. See
> \url{http://www.fs.fed.us/psw/programs/ecology_of_western_forests/projects/conifers/}
>
> }
>
> \author{Jeff D. Hamann \email{jeff.ham...@forestinformatics.com},\cr
> Martin W. Ritchie \email{mritc...@fs.fed.us} }
>
> \seealso{ \code{\link{plants.smc}},
> \code{\link{plots.smc}}
> \code{\link{plants.swo}},
> \code{\link{plots.swo}},
> \code{\link{sample.data}},
> \code{\link{set.species.map}},
> \code{\link{set.variant}},
> \code{\link{smc}},
> \code{\link{summary.sample.data}},
> \code{\link{swo}},
> \code{\link{thin}}
> }
>
> \examples{
> library( rconifers )
> ## Example for SWO variant
> ## set the variant to the SWO variant and set species map
> ##set.species.map( set.variant(0) )
> set.variant(0)
>
> ## grow the data that was originally swo in the smc variant
> # load and display CONIFERS example plots
> data( plots.swo )
> print( plots.swo )
>
> # load and display CONIFERS example plants
> data( plants.swo )
> print( plants.swo )
>
> # create the sample.data list object
> sample.swo.3 <- list( plots=plots.swo, plants=plants.swo, age=3,
> x0=0.0,n.years.projected=0)
> class(sample.swo.3) <- "sample.data"
>
>
> }
>
> \keyword{models}
>
> and the WARNING:
>
> * checking Rd \usage sections ... WARNING
> Assignments in \usage in documentation object 'sample.data':
> x <- list(plots, plants, age = 0, x0 = 0, n.years.projected = 0)
> class(x) <- "sample.data"
>
> Functions with \usage entries need to have the appropriate \alias
> entries, and all their arguments documented.
> The \usage entries must correspond to syntactically valid R code.
> See the chapter 'Writing R documentation files' in manual 'Writing R
> Extensions'.
> * checking Rd contents ... OK
>
>
>
> Respectfully,
> Jeff.
>
>
> Jeff Hamann, PhD
> PO Box 1421
> Corvallis, Oregon 97339-1421
> 541-754-2457
> jeff.hamann[at]forestinformatics[dot]com
> jeff.d.hamann[at]gmail[dot]com
> http://www.forestinformatics.com
> http://en.wikipedia.org/wiki/Forest_informatics
>
> To ensure that your email is processed, include a subject entry in your email.
>
>
>
>
> On Jan 6, 2012, at 11:38 AM, Bryan Hanson wrote:
>
>> Jeff, quick question: is this a data set or a function you are documenting?
>> What you say sounds like it's data, but the Rd file reads more like a
>> function. Or are you trying to document a data format/object which stores
>> specific data sets?
>>
>> Let us know, and I'll bet the answer will appear pretty quickly. Bryan
>>
>> ***********
>> Bryan Hanson
>> Professor of Chemistry & Biochemistry
>> DePauw University
>>
>> On Jan 6, 2012, at 2:11 PM, Jeff Hamann wrote:
>>
>>> I'm trying to update a package and would like to crush a WARNING message
>>> for a clean build.
>>>
>>> I've been struggling with this question and haven't gotten any traction on
>>> the web either.
>>>
>>> I've got a document file (Rd) that contains the following \usage statement:
>>>
>>> \name{sample.data}
>>> \alias{sample.data}
>>>
>>> \title{CONIFERS forest growth model sample data}
>>>
>>> \description{ A list object of type \code{sample.data} stores all of
>>> the basic information about a \code{\link{data.frame}} object
>>> representing a sample of plants.}
>>>
>>> \usage{
>>> x <- list( plots=data.frame(), plants=data.frame(), age=0, x0=0.0,
>>> n.years.projected=0 )
>>> class(x) <- "sample.data"
>>> }
>>>
>>> When I run R CMD check [pkg], I get the following WARNING:
>>>
>>> * checking Rd \usage sections ... WARNING
>>> Assignments in \usage in documentation object 'sample.data':
>>> x <- list(plots, plants, age = 0, x0 = 0, n.years.projected = 0)
>>> class(x) <- "sample.data"
>>>
>>> Functions with \usage entries need to have the appropriate \alias
>>> entries, and all their arguments documented.
>>> The \usage entries must correspond to syntactically valid R code.
>>> See the chapter 'Writing R documentation files' in manual 'Writing R
>>> Extensions'.
>>> * checking Rd contents ... OK
>>>
>>> I'm not sure if there's a problem with the \alias section or the \usage
>>> section or both sections (I'm assuming this is the case).
>>>
>>> I've read the Chapter 2 of R-ext.pdf plenty and just can't seem to see
>>> where I'm blowing it.
>>>
>>> Respectfully,
>>> Jeff.
>>>
>>>
>>> Jeff Hamann, PhD
>>> PO Box 1421
>>> Corvallis, Oregon 97339-1421
>>> 541-754-2457
>>> jeff.hamann[at]forestinformatics[dot]com
>>> jeff.d.hamann[at]gmail[dot]com
>>> http://www.forestinformatics.com
>>> http://en.wikipedia.org/wiki/Forest_informatics
>>>
>>> To ensure that your email is processed, include a subject entry in your
>>> email.
>>>
>>>
>>>
>>>
>>>
>>> [[alternative HTML version deleted]]
>>>
>>> ______________________________________________
>>> R-devel@r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>>
>
[[alternative HTML version deleted]]
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
