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.axens...@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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
