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

[Joris Meys]

Hi Barry,

could you specify wh osked you to provide examples? R CHECK doesn't give me
any warnings. If it was asked by the people of CRAN itself, you can explain
that these are internal functions and the help pages are only there for
reference to advanced users. But I'm not sure if they'll accept that. So
here's a few things you can do:

1. Remove the roxygen comment tag and just use #. The info stays in the
code file, but no help pages are generated for these functions. Do notify
CRAN when resubmitting that you removed these help files as these are all
internal functions.
2. Just add the most basic 1-line example to the help page to satisfy
CRAN's request.

Personally I more often use the second option, mainly to aid myself and
make it easier for people to understand how the code base works. But that's
personal flavour.
Cheers
Joris

On Mon, Aug 13, 2018 at 3:09 PM Eggleston, Barry <beggleston using rti.org> 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?
>
> Thanks,
> Barry
>
>         [[alternative HTML version deleted]]
>
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>


-- 
Joris Meys
Statistical consultant

Department of Data Analysis and Mathematical Modelling
Ghent University
Coupure Links 653, B-9000 Gent (Belgium)
<https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium&entry=gmail&source=g>

tel: +32 (0)9 264 61 79
-----------
Biowiskundedagen 2017-2018
http://www.biowiskundedagen.ugent.be/

-------------------------------
Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php

	[[alternative HTML version deleted]]