[R-pkg-devel] Undocumented requirement for CRAN

[Greg Hunt]

These aren't requirements of the language, they are issues of code and
documentation quality.  Other languages have exactly the same issues and no
code audit tool I've ever seen provides 100% coverage of potential issues.
There is always a level of human intelligence applied to effective code
review (I do know you can do code review without involving people but that
tends in practice to be fairly basic).  The CRAN process, human checking on
initial submission and a bit less on the later submissions seems like a
good balance of complexity and development effort.

Things like enforcing documentation of return values would require package
standards to be tightened.  That would cause problems for existing packages
and I don't think that there is specific markup for a return value anyway,
so detecting missing return value documentation either requires changes to
the underlying Rd markup, a bunch more intelligence in the check, or human
inspection.

The moment you document a function and explain how to get to it you have
committed to dealing with what happens when you change it.  Regardless of
whether its described as internal or publicly visible, people will use it
and they will get annoyed when you change it or when it is broken (which
may not matter to the internal use in the package but may be visible in
edge cases from outside).  If they have to go digging to find and
understand the internal interfaces its much clearer to them that they are
on their own.  Looked at another way, if the external interface is complete
then people don't need the internal interfaces.  If its incomplete then
thats an interface design problem.  I have seen distinction made between
general use programming interfaces and product (or release) sensitive
programming interfaces, but they come with statements about how they are
likely to change and what limited purposes they can be used for.  Thats a
more bureaucratic approach than R developers are likely to engage with.

Greg

On Tue, 13 Sept 2022 at 09:46, Jiří Moravec <jiri.c.moravec using gmail.com>
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.
>
> 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.
> (also, packages are not journal articles)
>
> Same with documentation, I can't spot and fix an issue, if I am not even
> aware that it is an issue.
>
>
>  > 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
>
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>

	[[alternative HTML version deleted]]