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

[Martin Maechler]

>>>>> Martin Morgan <martin.morgan at roswellpark.org>
>>>>>     on Sun, 15 May 2016 14:25:01 -0400 writes:

    > On 05/15/2016 02:20 PM, Dan Tenenbaum wrote:
    >> 
    >> 
    >> ----- Original Message -----
    >>> From: "Richard Cotton" <richierocks at gmail.com> To:
    >>> "bioc-devel" <bioc-devel at r-project.org> Sent: Sunday,
    >>> May 15, 2016 4:45:09 AM Subject: [Bioc-devel] \donttest
    >>> and the "80% of man pages documenting exported objects
    >>> must have runnable examples" rule
    >> 
    >>> 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).
    >>> 
    >>> 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.
    >>> 
    >> 
    >> 
    >> Ultimately, humans make all decisions about package
    >> inclusion. So you will have a chance to discuss your
    >> package with someone.

    > Examples traditionally have dual roles in illustrating
    > functionality and testing code. It would be particularly
    > favorable if you could point to other parts of your
    > package where the code was tested -- unit tests via RUnit
    > or testthat being a natural place, see
    > http://bioconductor.org/developers/how-to/unitTesting-guidelines/
    > -- and it's use illustrated -- vignettes or other
    > examples.

    > Martin

I also wonder *why*  you use \donttest{} so extensively.
It's clearly better than  \dontrun{}  (which really distresses
me, if used more than occasionally).

 I was involved 20 years ago ensuring that in R, almost all
help pages have examples *and* that all examples ran, and you
could use   example(<..>)  to let them run,  get quickly some
example objects into your R session, etc, etc, etc.

Hence, I've recently felt  chagrined repeatedly, seeing package
authors providing whole packages with no runnable examples..


the other Martin M
(Martin Maechler, ETH Zurich)