[R-pkg-devel] Undocumented requirement for CRAN

[Duncan Murdoch]

On 12/09/2022 6:42 p.m., Jiří Moravec wrote:
> There are quite a lot of undocumented requirement for CRAN.
> This bite me several times already.
> 
> They are not documented in the
> https://cran.r-project.org/doc/manuals/R-exts.html
> Nor they are marked by `R CMD check`
> 
> Ideally, these would be documented AND flagged by R CMD check.
> Otherwise, it is a waste of time for both CRAN team and package developers.
> 
> So far, the undocumented requirements that were flagged for me are:
> 
> * Documenting return value even for functions without return value
>     -- This is even contrary to the base code (i.e., many graphical
> functions do not document return values)
> 
> * Commented code in examples
> 
> * Examples for non-exported internal functions
>     -- I understand that this is related to the fact that any ::: is
> highly discouraged (which is documented) and that examples for
> unexported functions cannot be run without ::: .
>        But I like the idea of using properly documented internal
> functions and usage of examples as for rudimentary testing.
> 
> 
> Are there any other undocumented requirements?

Of course there are.  CRAN is not an automaton, it is a group of people 
who review your submission.

Your question is like asking whether there are any undocumented 
requirements for acceptance of a paper in a journal.  Of course there are!

What you should do is aim for perfection in what you submit.  If you can 
spot problems, fix them before you submit.  Documenting examples is an 
obvious case where the example is likely to be improved with better 
commenting.

Example code for non-exported functions seems to miss the point.  If a 
user can't count on the interface for those functions remaining 
unchanged, why document it in a user-visible place?  Put those kinds of 
docs as comments in the source code.  Or if they can count on the 
interface, then they should be exported functions.  You can test them 
using ::: if you want tests.

There are no functions without return values.  Sometimes the return 
value is an invisible NULL, but there is always a return value.  The 
fact that some base packages don't document this is a deficiency in that 
documentation, not an excuse for having a deficiency in your documentation.

Duncan Murdoch