[R-pkg-devel] Where do demos fit in?

[Neal Fultz]

A graduate student just asked me (copied below), in response to a bug I
wrote (
https://github.com/DeclareDesign/estimatr/pull/38/commits/99e82e253979d1307714632e9dc05d2e2c9c66df
):

How do demos normally relate to tests and vignettes? Is the purpose simply
> to have manually run tests that check the things work in the global
> environment?


...which is a fair and good question.

I replied:


> My current understanding is:



tests - verifies things aren't broken - implemented either via testthat or
> traditional tests in the test/ directory - run manually, by R CMD check, by
> CRAN, or by CI before build/shipping. End users typically don't run these.
>

demos - extended things a user might want to do, possibly interactive -
> basically just scripts that get source() as if a user had done so
> themself - run only when a user types demo()

vignettes - documentation mixed with code - usually supplemental to man
> pages and / or R-Journal or JSS articles - run at build time, static
> html/pdf file displayed when user types vignette(), also mirrored on CRAN
> IIRC.

examples - these live inside the function .Rd pages - for us they can come
> from a roxygen @examples <https://github.com/examples> block - run when
> the package is built, and when user runs example(foo) so to a large degree,
> there's a four-circle venn-diagram of where different snippets of code
> could live. For the particular NSE bug I caused, (where because of scoping
> a testthat passed where a demo would have failed), I think
> there's value in having and then testing demos.



Scoping bugs aside, R-exts.html describes all of these very procedurally,
and
it isn't completely obvious to me (or him) what current best practices
are...  Is
it dumb to have a test that calls demo?

Anyway, I've actually got a lot of value out of demos so far. If other
people feel that way,
I'd be happy to work on the tooling around them (roxygen indexes for
demos??? idk)
but if the trend is towards less demos and more of something else, I'd
follow that advice
also. (I also think there's a decent argument to be made that demos should
just be
functions, FWIW).


Thanks much,

-Neal
















PS hoping gmail sends this as plain text correctly...

	[[alternative HTML version deleted]]