From arppe at ualberta.ca  Wed Dec 18 18:08:21 2013
From: arppe at ualberta.ca (Antti Arppe)
Date: Wed, 18 Dec 2013 17:08:21 +0000
Subject: [Rd] Fwd: Bad \usage lines question
In-Reply-To: <52B1D5FA.5000400@ualberta.ca>
References: <52B1D5FA.5000400@ualberta.ca>
Message-ID: <52B1D685.6080209@iki.fi>

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"
        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

-- 
======================================================================
Antti Arppe - Ph.D (General Linguistics), M.Sc. (Engineering)
Assistant Professor of Quantitative Linguistics
Department of Linguistics, University of Alberta
E-mail: arppe at ualberta.ca, antti.arppe at iki.fi
WWW: http://www.ualberta.ca/~arppe
Maanahtu ina reed?ti ihza umm?nuuti ihannaq - dulum ugulak ?mun ingul



[Rd] Fwd: Bad \usage lines question
Antti Arppe