[R-pkg-devel] questions about \dontrun{} etc.

[Ben Bolker]

  {Sorry this is long, just trying to be clear and thorough.}

  I'm struggling a bit with some CRAN recommendations; would appreciate
opinions/suggestions about how other people would handle this case.

  I'm working on a package (https://github.com/bbolker/broom.mixed) that
processes model fits from lots of other packages.  The time taken to fit
the original model varies a lot, from a few seconds to several minutes.

 My typical framework for the examples looks something like this:

if (require("lme4")) {
   \dontrun{
      lmm1 <- lmer(Reaction ~ Days + (Days | Subject), sleepstudy)
   }
   load(system.file("extdata","lme4_example.rda",package="broom.mixed"))
   <.... stuff ...>
}

or sometimes the \dontrun{}  would be replaced by a commented-out code
line instead,

   ## lmm1 <- lmer(Reaction ~ Days + (Days | Subject), sleepstudy)

 The purpose of these lines is to show readers what model was fitted to
produce the stored model object that's going to be processed.

  CRAN responded:

===
Please replace \dontrun{} by \donttest{} or unwap [sic] the examples if
they can be executed in less than 5 sec per Rd-file.

Please do not comment out examples.
===

I see that the deprecation of (¿ too strong; "preference for avoiding"
?) \dontrun{} was previously discussed here:
https://stat.ethz.ch/pipermail/r-package-devel/2018q2/002811.html : Uwe
Ligges responded

> Sure, \dontrun{} markup is intended for cases where neither automated
chercks nor users can expect that the given code work out of the box
and, e.g., changes are needed to make it work, e.g. isertion of otehr
useranmes ... while \donttest{} is expected to work out of the box
(perhaps code that only work interactively or excluded in order to omit
ling running examples from the checks). Nothing new here.

   My desiderata:

1. make CRAN happy
2. consistent format across examples
3. avoid having users run the long examples, even by accident; I
personally would find it a little frustrating if a cut-and-paste to try
out the examples resulted in a 5-minute run time ...
4. readability
5. not letting examples get out of sync, e.g. because of downstream
package changes [I do have code for updating all of the fitted examples
at once, but it's not run automatically]

 * My preference would be for using \dontrun{} universally (consistent,
readable, mostly avoids accidental runs), but this goes against
(informal?) CRAN policy

 * universal \donttest{} doesn't seem to do what I want, since I *do*
want to avoid users having to run long examples

  * commenting (with something like "original model:" to make it clearer
that it's not a commented-out example) is even better for avoiding
accidental runs (harder to accidentally cut-and-paste, if doing that
rather than using example()), but less readable.

  * putting slow model fits in \dontrun{} and letting fast model fits be
executed does what CRAN asks and helps avoiding example-drift, but is
less consistent -- and I can't be sure that a model fit won't take much
longer on one of CRAN's test machines ...

  Thoughts?

  cheers
   Ben Bolker