From arne.henningsen at googlemail.com  Fri Jul 18 08:05:07 2008
From: arne.henningsen at googlemail.com (Arne Henningsen)
Date: Fri, 18 Jul 2008 08:05:07 +0200
Subject: [Rd] Checking package help file examples
In-Reply-To: <Pine.GSO.4.56.0807171703500.13491@devsun3201.insightful.com>
References: <Pine.GSO.4.56.0807171703500.13491@devsun3201.insightful.com>
Message-ID: <200807180805.09930.arne.henningsen@googlemail.com>

On Friday 18 July 2008 02:19:14, Bill Dunlap wrote:
> I am trying to figure out the sanctioned way for
> 'R CMD check pkg' to make sure that the examples
> in help files give the expected results.
>
> Writing R Extensions says that check runs the help
> file examples (which INSTALL extracts from pkg/man/*.Rd
> and puts into files in pkg/R-ex).  It looks like check
> concatenates all the example files, pkg/R-ex/*.R, into one
> file, pkg/pkg-Ex.R, which it runs to produce pkg/pkg-Ex.Rout.
> If there is an error running these files then check aborts.
>
> I don't seen anything in Writing R Extensions about
> checking that correct results were produced.  However,
> in R 2.7.0, check will compare pkg/pkg-Ex.Rout to
> pkg/tests/Examples/pkg/pkg-Ex.Rout.save, if the latter
> file is in your package source, and report any differences.
>
> I don't see any mention of this and was wondering if this
> method should be recommended or if there was a preferred
> way to check help file examples for correctness.  (It would
> be nicer if the example() function could also check for
> correctness, and the above method doesn't allow for that.)

I use *.R and corresponding *.Rout.save files in the subdirectory "tests" for 
checking packages (see e.g., packages systemfit, micEcon, 
sampleSelection, ...). I think that it is better to separate examples from 
testing, because IMHO there should be a few simple examples but tests should 
contain many different function calls with (partly) unusual arguments to 
check (nearly) the entire functionality of each function.

See also the manual "Writing R Extensions"
http://cran.r-project.org/doc/manuals/R-exts.html#Package-subdirectories
======================================
Subdirectory tests is for additional package-specific test code, similar to 
the specific tests that come with the R distribution. Test code can either be 
provided directly in a .R file, or via a .Rin file containing code which in 
turn creates the corresponding .R file (e.g., by collecting all function 
objects in the package and then calling them with the strangest arguments). 
The results of running a .R file are written to a .Rout file. If there is a 
corresponding .Rout.save file, these two are compared, with differences being 
reported but not causing an error. The directory tests is copied to the check 
area, and the tests are run with the copy as the working directory and with 
R_LIBS set to ensure that the copy of the package installed during testing 
will be found by library(pkg_name). 
======================================

Best wishes,
Arne

-- 
Arne Henningsen
http://www.arne-henningsen.name



[Rd] Checking package help file examples
Arne Henningsen