[R] Seemingly bizarre behavior in R CMD check

[Thomas Lumley]

On Fri, 27 Jul 2001, Bartz, Kevin wrote in part:
>                                               Apparently, R keeps very
> stringent requirements on its documentation's usage field. If it's anything
> other than myFunc(arg1, arg2...), codoc won't parse it correctly in its
> tempfiles. And the particular S code I was translating used chiefly example
> calls in its documentation's usage fields. Is this formatting an intended
> necessity? I know it ensures consistency but it's too often the source of
> cryptic errors.

This is intended. It makes sure that the help page contains all the
arguments in the correct order (for positional matching), which is usually
a good idea.

You can override the check in cases where it is not useful to have this
sort of usage example, by providing the function prototype in a \synopsis
section instead. help(abline) does this because the actual prototype would
be more confusing than what is given.

However, quite a lot of user-written S code comes with help pages that
don't document all the arguments or have the order of arguments wrong.
codoc at least checks this.

In most cases it really is better to put examples in the \examples section
and usage in the \usage section.

	-thomas

Thomas Lumley			Asst. Professor, Biostatistics
tlumley at u.washington.edu	University of Washington, Seattle

-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-help-request at stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._