[Bioc-devel] EXTERNAL: Not possible to create runnable examples for package

[McDavid, Andrew]

Hi Kelsey,

1. If you are writing a wrapper, then do all the intermediate steps need to be exposed and exported to the end user?  If you don't @export a function, you don't need an example (though it can still be useful to write one for your own purposes).   If the intermediate steps do need to be exported, then users (including, in my own experience, myself 6 months from now ;) ) will have a hard time understanding the format or state requirements if there aren't self-contained examples they can run.
2.  If the data is large, can you find a way to use a very minimal, perhaps even simulated, toy example to illustrate the functionality?  The package scater does a good job of this, IMO.  They use a purpose-built function for generate small, but illustrative example data. For instance, https://rdrr.io/github/davismcc/scater/src/R/plotRowData.R. You might also read about ways to mock objects, though I think this would be more appropriate to mimic external services rather than the scenario you describe here.
3.  With roxygen2, you can factor out repeated code using the @example tag, which includes code from an external file. For instance see https://github.com/amcdavid/CellaRepertorium/search?q=small_cluster_example.R
4.  If it's difficult to write examples for functions that are part of the exported interface, it can be a sign that the interface needs to redesigned.

So in summary, I don't think it's a good idea to waive this requirement if you want others to be able to easily use your package.  If you share a repository, others might be able to chime in with more specific suggestions about the interface design.


Andrew McDavid

Biostatistics and Computational Biology
University of Rochester Medical Center

On 8/10/21 11:48 AM, Kelsey Chetnik via Bioc-devel wrote:
I am preparing a package for submission to Bioconductor. One of the errors I got from running BioCheck() was "At least 80%of man pages documenting exported objects must have runnable examples". The way our package is constructed makes meeting this requirement practically impossible.

Our package is designed to create pipelines by chaining functions and saving intermediate results in an object. These functions are not meant to be run in small examples - many require a series of other functions to be run before they can be called. It wouldn't be possible to make the examples runnable without either large intermediate objects that would cause our package to exceed the size limit of 5 MB or long examples that could consist of 20+ lines of code. It would also be very complicated and difficult to maintain these examples.

Is it possible for our package to be accepted without resolving this issue if we provide justification for it?


	[[alternative HTML version deleted]]