[Rd] Fwd: Bad \usage lines question

[Duncan Murdoch]

On 18/12/2013 12:08 PM, Antti Arppe wrote:
> Dear colleagues,
>
> In checking a function I am adding to an R package, I get the following
> warning pair:
>
> ...
> Bad \usage lines found in documentation object 'nominal':
>     "\\method{print}{nominal}"(x, max.print = 10,
>        posthoc = "std.pearson.residuals.sign",
>        assoc = ifelse("univariate"

Notice how the line above differs from your source -- the % signs are 
taken as comment markers.  You need to escape them.

Duncan Murdoch

>          list(c("N", "alpha.X2", "uc.12", "uc.21")),
>          list(c("N1", "N2", "N12", "uc.12", "uc.21"))),
>        sort.key = NULL, ...)
>     "\\method{summary}{nominal}"(object, posthoc =
> "std.pearson.residuals.sign",
>        assoc = ifelse("univariate"
>          list(c("N", "alpha.X2", "uc.12", "uc.21")),
>          list(c("N1", "N2", "N12", "uc.12", "uc.21"))),
>        sort.key = NULL, ...)
>
> 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 functions are described in the (same) manual page document file as
> follows:
>
> ---- nominal.Rd -----
> \name{nominal}
> \alias{nominal}
> \alias{print.nominal}
> \alias{summary.nominal}
> \alias{print.summary.nominal}
>
> \title{
>     Univariate and bivariate statistics for categorical,
>     unordered variables
> }
> \description{
>
>     \code{nominal} takes a data frame with categorical (i.e. nominal)
>     variables and calculates a range of categorical statistics and
>     posthoc analyses.
>
> }
> \usage{
> nominal(formula, data, sort.bivariate = NULL, std.pearson.residual.min = 2,
>      correct = FALSE, report.interval = 100, transform.variables = FALSE)
>
> \method{print}{nominal}(x, max.print = 10,
>      posthoc = "std.pearson.residuals.sign",
>      assoc = ifelse("univariate" %in% class(x),
>        list(c("N", "alpha.X2", "uc.12", "uc.21")),
>        list(c("N1", "N2", "N12", "uc.12", "uc.21"))),
>      sort.key = NULL, \dots)
>
> \method{summary}{nominal}(object, posthoc = "std.pearson.residuals.sign",
>      assoc = ifelse("univariate" %in% class(object),
>        list(c("N", "alpha.X2", "uc.12", "uc.21")),
>        list(c("N1", "N2", "N12", "uc.12", "uc.21"))),
>      sort.key = NULL, \dots)
>
> \method{print}{summary.nominal}(x, max.print = 10, \dots)
>
> }
> ...
> -----
>
> The functions themselves are described as follows:
>
> ----- nominal.R -----
> print.nominal <- function(x, max.print=10,
> posthoc="std.pearson.residuals.sign", assoc=ifelse("univariate" %in%
> class(x), list(c("N","alpha.X2","uc.12","uc.21")), list(c("N1","N\
> 2","N12","uc.12","uc.21"))), sort.key=NULL, ...)
> ...
>
> summary.nominal <- function(object,
> posthoc="std.pearson.residuals.sign", assoc=ifelse("univariate" %in%
> class(object), list(c("N","alpha.X2","uc.12","uc.21")), list(c("N1","N2"\
> ,"N12","uc.12","uc.21"))), sort.key=NULL, ...)
> ...
> -----
>
> I've checked that the function specifications in the code match the
> specifications in the manual page, and that all the arguments are
> described in the manual page as well. The problem did not disappear when
> I separated the summary method and its corresponding print method to a
> separate file. I suppose the only difference between the code and the
> manual pages is that in the manual pages I've tried to make the line
> widths narrower (so there are differences in terms of space or newlines,
> but nothing else).
>
> But when building the package and installing it, everything appears fine
> within R, whether using the terminal or GUI versions.
>
> Am I missing something here, or what? Any suggestions or pointers will
> be much appreciated.
>
> Thanks, -Antti Arppe
>