[R-pkg-devel] [patch] R CMD check when there are no .Rd examples

[Neal Richardson]

Thanks for the explanation. Is it possible for R CMD check to
distinguish between packages for which examples do or do not make
sense, and raise a "Note" as appropriate?

I really don't mean to make a big issue out of this particular (soft)
requirement--it was easy enough for you to spot and easy enough for me
to fix. But, this is the third or fourth time over the last few years
that I've submitted a package that passes R CMD check but have had to
revise and resubmit due to a similar minor requirement. I rely on
automation and tools, particularly R CMD check, to enforce
requirements so that I don't have to remember all of the subtleties of
"Writing R Extensions" and other policies. Yet, I now have a growing
list of additional checks that I have to remember to go through before
submitting, and it's easy to forget.

If 'R CMD check --as-cran' passes and CRAN rejects, it seems that the
tool is incomplete, and if it's feasible to improve it, we should. I'm
happy to try to prepare a different patch that better encapsulates
this particular policy.

Neal

On Wed, May 10, 2017 at 9:59 AM, Uwe Ligges
<ligges at statistik.tu-dortmund.de> wrote:
> There are packages where examples do not make sense, hence we do not
> generally reject such packages.
>
> But if adding examples are reasonable we ask for them.
>
> Best,
> Uwe Ligges
>
>
>
>
> On 10.05.2017 17:28, Neal Richardson wrote:
>>
>> Hi,
>> Last week I submitted a new package to CRAN, and it was rejected
>> because there were no examples in any of the man pages. That's a
>> reasonable requirement--I just didn't know it was one. When I looked
>> back at the R CMD check results locally, I saw
>>
>>     * checking examples ... NONE
>>
>> but the run still finished with
>>
>>     Status: OK
>>
>> so I believed that my package was good. The package did have usage
>> examples in the test suite and on the readme file, and it was no
>> problem to copy the examples over to a man page and resubmit. But it
>> seemed like an unfortunate and avoidable waste of the CRAN
>> maintainers' time to have to ask for revisions and review again.
>>
>> I read the source and saw that the requirement around .Rd examples
>> that R CMD check does enforce is only when there are no examples, no
>> vignettes, and no tests
>>
>> (https://github.com/wch/r-source/blob/trunk/src/library/tools/R/check.R#L5100-L5117).
>> The attached one-line patch makes the check for .Rd examples now log a
>> "Note" rather than just print "NONE". Running it against my package
>> without man-page examples, it shows
>>
>>     * checking examples ... NOTE
>>     No examples
>>
>> and ends with
>>
>>     Status: 1 NOTE
>>
>> which should be enough to remind package authors to address it before
>> submitting to CRAN.
>>
>> Thanks for considering this patch.
>>
>> Neal
>>
>> P.S. Since this is an issue about CRAN policy and package development,
>> I thought R-package-devel was the appropriate list to email, but
>> please let me know if I should send the patch to R-devel instead.
>>
>>
>> patch.diff
>>
>>
>> Index: src/library/tools/R/check.R
>> ===================================================================
>> --- src/library/tools/R/check.R (revision 72665)
>> +++ src/library/tools/R/check.R (working copy)
>> @@ -2868,7 +2868,7 @@
>>                                   " check also with --run-donttest\n")
>>                  }
>>              } else {
>> -                resultLog(Log, "NONE")
>> +                noteLog(Log, "No examples")
>>                  no_examples <<- TRUE
>>              }
>>          }
>>
>>
>>
>> ______________________________________________
>> R-package-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>>
>