Skip to content

Seemingly bizarre behavior in R CMD check

3 messages · Bartz, Kevin, Thomas Lumley, Brian Ripley

Original
Bartz, Kevin
# 
Maybe someone can help shed some light on an odd and repeatedly irritating
error I noticed when running the check Perl script on my R 1.3 project. In
following it line by line, I traced my problem down to the
code/documentation matching within check, the most recent version of which
seems to verify proper .Rd formatting by means of R's codoc and undoc
functions. Under R --vanilla, those two then unpack and repack my project,
with each assembling a kind of test tempfile to ensure various structural
requirements within my project. At first, I got bogged down in a mysterious
"parse" problem, R's not-too-revealing result of a simple eval, but after
discovering the keep.tempfiles flag I was able to trace the obvious errors
without running codoc line by line interactively. 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. 

Anyway, fixing these usage fields worked for the time being but without fail
another similar problem soon emerged, this time with the check for
undocumented objects. This leg of the script uses undoc, and after
examination I found that undoc's concatenation of the R code in the
project/R directory fails to insert a newline at the end of each .R file's
contribution to the appended tempfile. Now I'm a clean kind of guy and I
like to keep my code immaculate, so it was more than disturbing when my R
functions, each stored in a single .R file, bombed out because each did not
have a newline proceeding its closing bracket. Without that, undoc's file
appending sticks the next function right up against the last's final
bracket, triggering an obvious syntax error, albeit one hidden underneath
tempfiles and a parse/eval combo. Now I can understand somewhat the benefits
of establishing consistency in the usage fields, but for the life of me I
can't figure out the reasoning behind this seemingly superfluous stringency.
Is this R's intended behavior, and if so, forgive me for asking, but why?

Thanks in advance for any light you can cast on the issue.

Kevin
-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
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
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
Thomas Lumley
# 
On Fri, 27 Jul 2001, Bartz, Kevin wrote in part:
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
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
Brian Ripley
#
On Fri, 27 Jul 2001, Bartz, Kevin wrote:

            

      
      
      
    

        
Do you mean a newline *after* the closing brace (to be precise)?  That
would explain the rest of the sentence.  A well-formed .R file *does* have
a final newline, so `immaculate' code should have one.  (BTW, the
tidying-up procedure mentioned in `Writing R Extensions' does ensure a
final newline.)

            

      
      
      
    

        
(Assuming I have decoded your explanation correctly.)  Because Unix text
files do have a final newline.  It's a very widespread convention, and the
most widespread editor, vi, enforces it.  Now undoc could be asked to
insert a newline (and given your experience it is probably a good idea) for
files which lack one, but this has not arisen in the hundreds of packages
which have been tested to date.