Man pages with runnable examples calculation
1
0
Entering edit mode
@lizingsimmons-6935
Last seen 4.1 years ago
Germany

BioCCheck is complaining that < 80% of man pages having runnable examples. The man/ directory of the package contains 39 *.Rd files, and there are 7 that BioCCheck lists as having no runnable examples.

I have three questions about the results:

  • 32/39 = 82.1% of man pages with examples, no? Although 4 of the man pages are for data, so maybe these aren't included and it's 28/35 = 80%?
  • One of the man pages without an example is for a deprecated function. Based on this page I thought deprecated functions shouldn't have examples. Maybe I haven't correctly marked it as deprecated?
  • One of the man pages without an example is brief documentation for the package itself. Does this need examples?

It'd be great to get some clarification about which .Rd files are included / excluded when calculating the % with runnable examples.

The package code is available on Github.  For reference here's the exact message I get from BioCCheck:

* Checking exported objects have runnable examples...
    * REQUIRED: At least 80% of man pages documenting exported objects must have
      runnable examples.The following pages do not:
      annotateAnchors.Rd, countsBetweenAnchors-methods.Rd,
  GenomicInteractions-package.Rd, GenomicInteractions-subsetByFeatures-methods.Rd,
  get_binom_ligation_threshold.Rd, get_self_ligation_threshold.Rd, removeDups.Rd
BiocCheck • 2.1k views
ADD COMMENT
1
Entering edit mode
Dan Tenenbaum ★ 8.2k
@dan-tenenbaum-4256
Last seen 6 months ago
United States

This is probably a question for bioc-devel, but anyway.

This particular check only cares about objects  (functions, methods, or data) that are exported (in your NAMESPACE) and whether they have examples. 

It's always good to have examples, even for a general package page, whose example could just show how to load the package.

Data objects should have examples too, even if it's just how to load the data object.

R (and BiocCheck) knows nothing about Bioconductor's way of deprecating functions. So ultimately if BiocCheck is complaining about a function that is deprecated you can ignore the warning for that particular page.

 

ADD COMMENT
0
Entering edit mode

Ah, I just realised that one of those Rd files refers to a function which I thought was exported but isn't, so it's 27/34 = 79.4%...

I can add an example to the package man page. The data objects don't have examples, but aren't listed as not having examples, but again that's easy to add and I'll do that.

About deprecation - I misread this page previously and now I realise that it says R CMD check, not BioCCheck, should report use of a deprecated function in examples, but your comment suggests this wouldn't be the case?

ADD REPLY
0
Entering edit mode

Actually I think I misspoke about the deprecated functions. You are right that R CMD check, not BiocCheck, will report the use of a deprecated function in examples.

ADD REPLY

Login before adding your answer.

Traffic: 574 users visited in the last hour
Help About
FAQ
Access RSS
API
Stats

Use of this site constitutes acceptance of our User Agreement and Privacy Policy.

Powered by the version 2.3.6