[Rd] missing documentation entries ... WARNING
Luis Rodriguez
luis.f.rodriguez1 at gmail.com
Mon Oct 28 21:00:30 CET 2013
Aha… I think I have taken care of this.
My team just realized that a class level documentation Rd file is required… I have created this with calls to the methods section, itemized… and we seem to be good to go.
Thanks!
~luis
On Oct 28, 2013, at 1:54 PM, Luis Rodriguez <luis.f.rodriguez1 at gmail.com> wrote:
> Dear Duncan and R-devel,
>
> This advice has cleared my "checking Rd \usage sections" warning—but I am not sure I did a good job taking your advice as I cleared this by modifying the alias statements, but not invoking \S3method or \S4method.
>
> Thus, I am still a bit stumped on my "checking for missing documentation entries … WARNING"
>
> It still reads:
>
> ***
> 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
> ***
>
> My updated \alias and \usage sections are included below.
>
> Based on some archived discussion board material I have read, I am considering adding a section that might read something like this for methods mod and plot, but my logic seems off as the error does not seem to respond to this addition:
>
> \section{Methods}{
> \describe{
> \item{mod}{\code{signature(object = "commcorrelogram")}: Provides a shortcut method for \code{mod.commcorrelogram}.}
> }
> }
>
> Does that make sense?
>
> What would you suggest?
>
> I will also work on correcting my approach to invoking \S3 and \S4method.
>
> Thanks!
> ~luis
>
>
> ****comcorrelogram.Rd \alias and \usage sections****
>
> \name{commcorrelogram}
> \docType{class}
> \alias{commcorrelogram}
>
> \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')
> }
>
> ****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',...)
> }
>
> ****mod.comcorrelogram.Rd \alias and \usage sections****
>
>
> On Oct 14, 2013, at 4:21 PM, Duncan Murdoch <murdoch.duncan at gmail.com> wrote:
>
>> 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
>>>>
>>>
>>
>
More information about the R-devel
mailing list