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

[Uwe Ligges]

On 13.08.2018 16:51, Duncan Murdoch wrote:
> 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.

Yes, please.
If marked internal and it is not exported, examples are not mandatory.

Best,
Uwe Ligges




> Duncan Murdoch
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel