[R-pkg-devel] Undocumented requirement for CRAN
On 12/09/2022 7:45 p.m., Ji?? Moravec wrote:
For experienced R developer like you, certain things might seem obvious without the need of any documentation. But please understand that other languages do not have such requirements. So for new people, or people coming from different languages, this might not seem as obvious as it is for you.
As Greg said, this isn't a language requirement. It's a publication requirement. You are free to ignore it if you don't want to publish your package on CRAN.
R already has a capability to do automated checking of packages to enforce certain level of quality. From this perspective, at least to me, it doesn't make sense that some issues are automatically flagged, while other issues, which might be on the same or lower level of complexity, are not.
The way this happens is that some packages (e.g. base packages, as you saw) are published before it is realized that something is actually a problem. To add the test will then trigger work for all those package authors to deal with it, and trigger work at CRAN to inform them and deal with the fallout from the authors who are slow to respond, or from authors who complain that the issue wasn't flagged in earlier versions of the tests. The ability to carry out this work is finite, so not all possible tests are implemented instantly. On the other hand, new submissions get manual examination, and so more stringent tests are possible.
(also, packages are not journal articles)
Obviously there are big differences, but the general concept of requiring a certain level of quality applies to both.
Same with documentation, I can't spot and fix an issue, if I am not even aware that it is an issue.
You are now aware of it. Duncan Murdoch
> If a user can't count on the interface for those functions remaining
unchanged, why document it in a user-visible place? Why not? Even unexported functions are user-visible through ::: . Since they are already documented, I might as well produce full documentation that is checked during `R CMD check`. Isn't one of the R's advantage the ability to read code of any function without wading through the source files?
> 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. That is good to know. I certainly know it now after having to fix this issue in my package. But how I am was supposed to know about it when this problem is not documented, `R CMD check` doesn't flag it, and official documentation uses it? -- Jirka On 9/13/22 11:19, Duncan Murdoch wrote:
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