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