[Rd] missing documentation entries ... WARNING

[Duncan Murdoch]

On 13-10-14 1:54 PM, Luis Rodríguez wrote:
> Thanks Duncan (and othersin R-devel).
>
> I clearly got away from this project, but I am still quite interested in resolving this issue and getting these codes into the CRAN.
>
> Some attempts to repair the documentation have occurred in the intervening time, so I am including slightly updated error messages and the relevant tops of the Rd files, as requested by Duncan. See below.
>
> Thanks again!
>
> ~luis
>
>
>
> <<<<my "missing documentation entries">>>>
>
> * checking for missing documentation entries ... WARNING
> Undocumented S4 classes:
>    ‘commcorrelogram’
> Undocumented S4 methods:
>    generic 'mod' and siglist 'commcorrelogram'
>    generic 'plot' and siglist 'commcorrelogram,missing'
> All user-level objects in a package (including S4 classes and methods)
> should have documentation entries.
> See the chapter ‘Writing R documentation files’ in the ‘Writing R
> Extensions’ manual.
>
> <<<<my "missing documentation entries">>>>
>
> I am also getting a * checking Rd \usage sections … WARNING, but your message makes me think this is related to the above. JIC, here is that error message:
>
> <<<<my "\usage section" Warning>>>>
>
> * checking Rd \usage sections ... WARNING
> Objects in \usage without \alias in documentation object 'commcorrelogram':
>    ‘plot.commcorrelogram’
>
> 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 the ‘Writing R
>
> <<<<my "\usage section" Warning>>>>
>
>
> ****comcorrelogram.Rd \alias and \usage sections****
>
> \name{commcorrelogram}
> \docType{class}
> \alias{commcorrelogram}
> \alias{mod,commcorrelogram}
> \alias{plot,commcorrelogram,missing}

Those aliases look like S4 documentation, not S3 as the comment states.
>
> \title{
>    Community Correlogram
> }
> \description{
> Function \code{commcorrelogram} computes community correlograms using either the multivariate Mantel statistic (Mantel, 1957) or the ANOSIM R metric (Clarke, 1993), and includes functionality for both directional analyses and combinations of temporal and spatial analyses.  Mantel correlogram proposed by Sokal (1986) and Oden and Sokal (1986). ANOSIM correlogram suggested here.
> }
> \usage{
> commcorrelogram(sampleData, sampleTime = NULL, sampleLocation = NULL,
>      LocationNames = NULL, option = 1, metric = "anosim", lagNumber, lagSize,
>      lagTol, numTests = 999, anisotropic = FALSE, azimuth, azimuthTol,
>      bandwidth, dipAngle, dipTol, dipBandwidth, distmeth = "bray",
>      mantmeth = "spearman", adj = "holm", prog = TRUE, alternative =
>      "one.sided")
>
> # S3 method for class 'community.correlogram'
> plot.commcorrelogram(x, y, alpha=0.05, …)
> }

You should use \S3method{plot}{commcorrelogram}(x, y, alpha = 0.05, ...) 
(or maybe \S4method ...).


>
> ****comcorrelogram.Rd \alias and \usage sections****
>
> ****mod.comcorrelogram.Rd \alias and \usage sections****
>
> \name{mod.commcorrelogram}
> \alias{mod.commcorrelogram}
> \alias{mod}
> \title{
> Community Correlogram Model
> }
> \description{
> Function mod.commcorrelogram automatically fits a Gaussian curve to the significance plot of a commcorrelogram object and calculates the correlation range of the data.
> }
> \usage{
> mod.commcorrelogram(object,Ch=1,Cc=5,Cw=0.01,plot=T,alpha=0.05
>    ,alternative='one.tailed',pw=5,lgpos='topleft',...)
> }

Again, use \S3method.

>
> ****mod.comcorrelogram.Rd \alias and \usage sections****
>
>
> On Sep 9, 2013, at 2:49 PM, Duncan Murdoch <murdoch.duncan at gmail.com> wrote:
>
>> On 09/09/2013 3:23 PM, Luis Rodríguez wrote:
>>> Dear R-devel,
>>>
>>> I am a relative novice in R, but I am eager to post a new package my group developed in CRAN, but I am stumped by a set of documentation related warnings created by R CMD check.
>>>
>>> So, my current plan is to recreate the documentation by religiously applying and modifying the skeleton codes that can be generated by R. In the meantime, I thought I'd post to the discussion group to see if maybe someone with more experience had some useful advice. Below you'll see a snippet of the key documentation warnings that we are stumped on.
>>>
>>> lagSelect and mod are functions created by my group, as is commcorrelogram. My belief is that they are clearly documented, but I suspect that our novice source code and documentation is not quite hitting what R CMD check is looking for.
>>
>> This message usually indicates that you don't have the relevant \alias{} defined correctly. If you do, please post the top of one or two of the Rd files, and we can tell you what's missing.  (I'd like to see at least the \alias{} and \usage{} sections.)
>>
>> Duncan Murdoch
>>
>>>
>>> If anyone has advice on how to pass R CMD check, it would be greatly appreciated.
>>>
>>> ~luis
>>>
>>>
>>>
>>> ***
>>> * checking for missing documentation entries ... WARNING
>>> Undocumented code objects:
>>>    ‘lagSelect’ ‘mod’
>>> Undocumented S4 classes:
>>>    ‘commcorrelogram’
>>> Undocumented S4 methods:
>>>    generic 'mod' and siglist 'commcorrelogram'
>>>    generic 'plot' and siglist 'commcorrelogram,missing'
>>>
>>> ***
>>> ______________________________________________
>>> R-devel at r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>