[Rd] R CMD check WARNING \usage question

[Duncan Murdoch]

  On 12-01-06 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.

You are documenting "sample.data", according to the name and alias.  But 
you create an object called "x".  There is no object (function or data) 
called "sample.data".  It's the name of an S3 class.

Now, there isn't a \docType setting for documenting an S3 class; they 
are usually documented along with the function that produces them.  So 
the easiest thing to do is probably to create a function (called 
sample.data, if you like) that produces the object, and document its usage.

Alternatively, don't use Rd for your documentation, write a vignette. 
But that's a lot more work.

Or create a prototype sample.data object (which is what your x looks 
like, being mostly empty), and document it using \docType{data}.  Move 
the code from your \usage section to \examples.

Duncan Murdoch

>
> 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.hamann at forestinformatics.com},\cr
> 	     Martin W. Ritchie \email{mritchie at 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 at r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>>
>
>
> 	[[alternative HTML version deleted]]
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel