[Rd] pesky \usage-warnings with R CMD check

[Peder Axensten]

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.

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}
——————————————————————————————————