[Rd] pesky \usage-warnings with R CMD check
Peder Axensten
Peder.Axensten at slu.se
Mon Dec 2 23:25:24 CET 2013
Duncan,
As soon as I read your letter I realized the logic. I followed your advice and the warnings are gone. I don’t know how long it would have taken me to see it myself, but probably quite some time – thank you!
I do think it’s a pity, in this special case, that I can’t put the returning function inside \usage. It would have made the documentation more clear and concise.
Best regards,
Peder Axensten
Research engineer
Swedish University of Agricultural Sciences
Department of Forest Resource Management
Remote Sensing
SE-901 83 Umeå
Visiting address: Skogsmarksgränd
Phone: +46 90 786 85 00
peder.axensten at slu.se, www.slu.se/srh
The Department of Forest Resource Management is environmentally certified in accordance with ISO 14001.
On 2 dec 2013, at 17:26, Duncan Murdoch <murdoch.duncan at gmail.com> wrote:
> On 02/12/2013 9:57 AM, Peder Axensten wrote:
>> I’m in the process of preparing a package for CRAN.
>>
>> The package is called “exportR” and since it really just consists of one function, I found it natural to call it “exportR” too.
>>
>> The function returns a function that does the actual job, but it is set up to work in different ways, depending on the arguments given to its creator. In short:
>> library( exportR )
>> exporter <- exportR( the, arguments )
>> exporter( its, own, arguments )
>>
>> When I run R CMD check I get two warnings:
>> -----------------
>> * checking for code/documentation mismatches ... WARNING
>> Functions or methods with usage in documentation object 'exportR' but not in code:
>> exporter
>>
>> * checking Rd \usage sections ... WARNING
>> Assignments in \usage in documentation object 'exportR':
>> exporter <- exportR(fname, type = "latex", format = "4", prefix = "",
>> append = FALSE)
>>
>> 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
>> Extensions’ manual.
>> ————————
>>
>> The first warning I understand, but I don’t know how to proceed to rid myself of it. Indeed it is nowhere in my code, as exportR creates it, but I still need to document it. I would very much appreciate advice.
>
> You should put exportR in your usage section, not exporter. To document exporter, you have at least a couple of choices:
>
> 1. The most straightforward way is simply to document it in the Details section of the help page. You can write what
> you like there; syntax of the help text will be checked, but not content.
>
> 2. You could actually run exportR in your package .R file, and create and export an exporter function. This will only make
> sense if there's a simple default one that would make sense for all users. But if you do that, then you can include exporter(its, own, arguments) in the usage section, and in the value section, say that the result of exportR will be a function that looks like exporter.
>
> You should not include an assignment in your usage section. I think it is being seen as a call to the "<-" function, so you get the warning about documenting something that is not an alias. (I might be wrong about the last part of the warning, I haven't looked closely.)
>
> Duncan Murdoch
>
>>
>> The second warning I don’t understand. I do have both \name{exportR} and \alias{exportR} (as well as \alias{exporter}) at the top of the .Rd file. The function name, arguments, and default values are copied directly from the source, so they are identical. I changed the package name to exporteR to see if the problem was that the package name and the function name were the same, but that did not remove the warning. I used package.skeleton to create a .Rd template for the function and it was syntactically identical. Installing the package and running it works, obviously. I’m running out of ideas and any help is appreciated. I have this nagging feeling that I’m missing something obvious…?
>>
>> I post the entire contents of the .Rd file at the bottom.
>>
>> Best regards,
>>
>> Peder Axensten
>> Research engineer
>>
>> Swedish University of Agricultural Sciences
>> Department of Forest Resource Management
>> Remote Sensing
>> SE-901 83 Umeå
>> Visiting address: Skogsmarksgränd
>> Phone: +46 90 786 85 00
>> peder.axensten at slu.se, www.slu.se/srh
>>
>> The Department of Forest Resource Management is environmentally certified in accordance with ISO 14001.
>>
>> ——————————————————————————————————
>> \name{exportR}
>> \alias{exportR}
>> \alias{export}
>> \alias{exporter}
>> \alias{latex}
>> \alias{conversion}
>> \alias{exportR.latex}
>> \title{Easy export of R results}
>> \description{A flexible and simple way to export R results to LaTeX and [maybe later] other formats.}
>> \usage{
>> exporter <- exportR( fname, type="latex", format="4", prefix="", append=FALSE )
>> exporter( ..., format=NA, prefix=NA, named=FALSE )
>> }
>> \arguments{
>> \item{...}{The value[s] to be exported. To name them, use the normal R convention: \code{exporter(first=123, second=456)}. If no such name is given, the variable name is used: \code{exporter(myvar, second=456)}. For other expressions the naming is undetermined, be sure to name them: \code{exporter(myname=2*pi/sqrt(2))}. Non-valid characters will be substituted by \code{x}, i.e. \code{my_var1} will result in \code{\\myxvarx} in LaTeX.}
>> \item{fname}{The path to the destination file.}
>> \item{type}{The name of export file type, e.g. \code{exporter}. May be a string vector to export to more than one format at once. But presently, only \code{exporter} is implemented.}
>> \item{format}{The numerical format to use. When given to \code{exportR}, it sets the default \code{.format} to be used by \code{exporter}. When used in a call to \code{exporter}, it is used for the present value[s]. The number suffix is the number of significant digits to use. The formats are: \tabular{llll}{
>> \tab Format \tab Example \tab \cr
>> sprintf expression \tab \%<expr.> \tab \%.5e \tab 10000*pi -> 3.14159*10^4\cr
>> flexible \tab <n> \tab 8 \tab 10000*pi -> 31415.927\cr
>> integer \tab i \tab i \tab 10000*pi -> 31415\cr
>> float \tab f<n> \tab f4 \tab 10000*pi -> 3.142*10^4\cr
>> float, factor 3 exponent \tab e<n> \tab e4 \tab 10000*pi -> 31.42*10^3\cr
>> float, with suffix \tab s<n> \tab s4 \tab 10000*pi -> 31.42 k\cr
>> float, with 2^10 suffix \tab b<n> \tab b3 \tab 10000*pi -> 12.06 Ki\cr
>> fraction \tab d or d<n> \tab d6 \tab pi -> 1146408/364913\cr
>> fraction, with integer \tab D or D<n> \tab D6 \tab pi -> 3+51669/364913\cr
>> }
>> }
>> \item{prefix}{If a naming prefix is to be used. When given to \code{exportR}, it sets the default \code{.prefix} to be used by \code{exporter}. When used in a call to \code{exporter}, it is used for the present and following value[s].}
>> \item{append}{If \code{TRUE}, values will be appended to the \code{fname} file, instead of rewriting it.}
>> \item{named}{If \code{TRUE}, the row names of a 2-d data structure (i.e. a \code{data.frame}) will be included as the first column. if \code{TRUE}, the item names of a 1-d data structure (i.e. a \code{list}) will be included.}
>> }
>> \details{
>> It's actually the function returned by \code{exportR} that does the job, so typically \code{exportR} is called only once. But more than one such function can be active at the same time.
>>
>> When the returned function (called \code{exporter}, above) is created, a header is written to the file \code{fname}. During subsequent calls, actual values are appended to the file.
>>
>> Presently, the following classes are recognized: \code{NULL}, \code{logical} (including \code{NA}), \code{character}, \code{factor}, \code{call} (it's evaluated through \code{eval}), \code{numeric} (including \code{INF} and \code{NaN}), \code{complex} (including \code{INF}), \code{matrix}, \code{array}, \code{list}, \code{pairlist}, \code{table}, \code{data.frame}, \code{lm}, \code{randomForest}, \code{randomForest.formula}, \code{ts}, \code{bigz} and \code{bigq} from package \code{gmp}, \code{int64} and \code{uint64} from package \code{int64}, and \code{integer64} from package \code{bit64}. Other classes are processed with \code{as.character( value )}.
>>
>> Table-like structures defines three commands for each structure:
>> \code{nameColumns,} that can be used as a column-format,
>> \code{nameHeader,} contains the column names, and
>> \code{nameBody} contains the actual table contents.
>> Example: \code{\\begin{tabular}{\\nameColumns}\\nameHeader\\hline \\nameBody\\end{tabular}}
>>
>> Some structures, like \code{lm}, may define even more variants. Try, and see what is generated!
>>
>> Support for more classes can be implemented by defining functions \code{as.exportR.<your-class>}. Call \code{as.exportR} on each item in your class to get the correct output. See \code{as.exportR.lm} in file \code{R/exportR.R} as an example on how to do this.
>>
>> Output formats presently supported: only \code{LaTeX}. Support for more formats can be implemented by writing a function \code{exportR.<your-format>} in the same manner as \code{exportR.latex}, present in the file \code{R/latexR.R}.
>> }
>> \value{
>> \code{exportR} returns a function that is used to output formatted values.
>>
>> This [returned] function returns no value, when called.
>> }
>> \author{Peder Axensten}
>> \examples{
>> library(exporteR)
>> ltx <- exportR( tempfile( pattern = "test", fileext = ".tex" ) )
>>
>> x <- 2*pi
>> ltx(x) # Writes \newcommand{\x}{6.283}
>> ltx(two_pi=2*pi) # Writes \newcommand{\twoxpi}{6.283}
>>
>> # Alternatively, in one go:
>> ltx(x, two_pi=2*pi)
>> }
>> \keyword{export}
>> \keyword{latex}
>> \keyword{utilities}
>> \keyword{conversion}
>> ——————————————————————————————————
>>
>> ______________________________________________
>> R-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
More information about the R-devel
mailing list