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]]
_______________________________________________
Bioc-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/bioc-devel
