[Bioc-devel] \donttest and the "80% of man pages documenting exported objects must have runnable examples" rule

[Hervé Pagès]

Hi Richard,

On 05/15/2016 04:45 AM, Richard Cotton wrote:
> I have a package with a lot of examples in exported functions marked
> as \donttest.
>
> BiocCheck doesn't count these functions towards the target of having
> 80% of exported objects with runnable examples.  I do have more than
> 80% runnable examples; it's just that BiocCheck can't see them.  (For
> background, the package is mostly about file import, and it takes a
> second or two to import the sample files included in the package.
> Having examples that run for a couple of seconds is fine for users,
> but makes package testing very slow (once dozens of the example are
> run).

How many dozens of examples exactly are we talking about? If examples
take only "a couple of seconds" to run, you can have hundreds of them
in your man pages and still remain under our 5 minute limit for
'R CMD check'.

I notice that you're using \donttest and not \dontrun though. Are you
saying that the time it would take to run all the examples is < 5 min
but even that is still a burden for you as a developer when you test
your package with 'R CMD check'? I could understand that argument and
maybe we could run 'R CMD check' with the --run-donttest option on the
build system. That way you could keep your examples in \donttest and
have a fast manual 'R CMD check' when you work on your package, but all
the examples would be checked by our build system (or by you when you
run 'R CMD check' with --run-donttest).

Cheers,
H.

>
> This check is considered REQUIRED to be solved, so I'd like to know if
> it's OK to include an explanation about the use of \donttest during
> submission, or if my pacakge will just get rejected outright.
>

-- 
Hervé Pagès

Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M1-B514
P.O. Box 19024
Seattle, WA 98109-1024

E-mail: hpages at fredhutch.org
Phone:  (206) 667-5791
Fax:    (206) 667-1319