[R-pkg-devel] Proper way to document helper functions not accessible by user.

[Duncan Murdoch]

On 13/08/2018 9:08 AM, Eggleston, Barry wrote:
> Hello,
> 
> I am working through my first submission and making good progress with the CRAN review system, but now I need to understand the best practice for dealing with helper functions.  I am building a package that only exports 12 functions for direct user access, but it has many helper functions not directly accessible to the user.  In my R code I am using roxygen2 to write my help pages.  I have written roxygen2 notes to create help pages for every function, but for all the helper functions I am using the keyword 'internal' so they don't show up in the index of help pages and available functions.  In future releases I may export these functions for direct access, but for now I want to keep them internal.  Within each help page of these non-accessible helper functions, I have placed '#None' in the @examples section, since nobody will be able to call the functions directly.  In my submission review I was asked to give examples for these functions, because my package still has the .Rd files f
>   or these helper functions in the submitted .tar.gz file.  How do I proper handle documentation of these helper functions?  Can I remove the roxygen2 notes that create the .Rd files for these helper functions, so the package does not contain .Rd files for them?
> 

This sounds like a bug in the review system.  Marking them with 
\keyword{internal} is how you are supposed to mark internal-use 
functions.  Most such help pages (e.g. ?layout.heights from the grid 
package) don't have examples.

If you got the message from a human being, you could just resubmit with 
a note pointing out that those pages are marked as internal.  If it was 
from the automatic checks, it's probably best to try one of the 
workarounds that someone else suggested.

Duncan Murdoch