[R-pkg-devel] What To Include In \donttest{}

[Iñaki Ucar]

On Thu, 27 May 2021 at 06:10, Danielle Maeser <maese005 using umn.edu> wrote:
>
> Thank you for your assistance. The link is very helpful.
>
> However, I am still not sure what the difference is between the example
> provided with \donttest{} and a vignette. It seems both display an example
> of the function. For instance: the example below seems not too different
> from a vignette:
>
> \donttest{
> name_of_function(parameters...)
> }

Vignettes constitute a complex form of documentation in which you
provide use cases, and thus demonstrate the interrelation between
several functions in your package to solve them with a lot of context.
Examples in the manual are very short and focused, and show how to run
a particular function in a minimal setup, usually without much
context. And you shouldn't use \donttest in general, unless a
particular example needs a long time to run.

CRAN is simply asking you to add examples in your manual pages for all
the functions in your package.

> Additionally, in order to set the parameters for this example in
> \donttest{}, it seems I must include data for this function inside of the
> man folder, which seems odd. I thought CRAN would ignore whatever code is
> provided in \donttest{} (therefore, I wouldn't have to provide the data
> here); however, the CRAN check complains that it does not know what these
> parameters are (aka object 'parameters' is not known).

All the examples must be runable and must succeed, even those enclosed
in \donttest. If your functions require some data to run, then the
most sensible thing to do is to include a small sample of data in your
package that you can then use in your examples. See "1.1.6 Data in
packages" in the "Writing R Exensions" manual on how to do this.

Iñaki

> On Wed, May 26, 2021 at 9:37 PM Dirk Eddelbuettel <edd using debian.org> wrote:
>
> >
> > Danielle,
> >
> > On 26 May 2021 at 21:23, Danielle Maeser wrote:
> > | Please excuse the very simple question, but I received the following
> > | message from a CRAN maintainer, and I am not sure what code to include
> > | inside of the \donttest{}. This is meant to enclose code that typically
> > | should be run, but not during package checking, and I do not have any
> > such
> > | code.
> > |
> > | Here is the message from the CRAN maintainter:
> > |
> > | *Please add small executable examples in your Rd-files to illustrate
> > theuse
> > | of the exported function but also enable automatic testing.Otherwise, you
> > | can also write some tests. Lengthy examples (> 5 sec) canbe wrapped in
> > | \donttest{}.*
> > |
> > | I'd appreciate any assistance you can provide.
> >
> > The quote contains three distinct sentences--with three distinct messages:
> >
> >   1. Please add examples, for both illustration and tests.
> >   2. You can also add tests directly (i.e. via directory tests/)
> >   3. Should examples run long, consider wrapping them in \donttest{}
> >
> > We can narrow this down to 'please add examples'.
> >
> > (Otherwise, a good trick is to search at GitHub in the (unofficial,
> > contributed) cran organization (mirroring CRAN) for terms you are
> > interested
> > in, here "\donttest" -- and this link claims 11k hits
> >   https://github.com/search?q=org%3Acran+%5Cdonttest&type=code
> > you can probably browse a few of these to get an idea.
> >
> > Hope this helps,  Dirk
> >
> > --
> > https://dirk.eddelbuettel.com | @eddelbuettel | edd using debian.org
> >
>
>
> --
> Ph.D. Student
> Bioinformatics and Computational Biology
> University of Minnesota
>
>         [[alternative HTML version deleted]]
>
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel



-- 
Iñaki Úcar