[R-pkg-devel] Inquiry

[Georgi Boshnakov]

>...functions, that are not meant to be called directly by users, should be documented in a file named <pkgnm>-internal.Rd.

This is one option, convenient in the use-case of the question. But why export a function that you actively don't want the users to know about? There are cases when this is needed or convenient but particularly with 'roxygen2' it is just about deleting an '@export' line.
 
Just for completeness, non-exported functions can be documented as any other functions. Adding

\keyword{internal}

will prevent them from appearing in manuals (but still accessible via '?'). Stating clearly that such functions are internal is also sensible. 


Georgi Boshnakov

-----Original Message-----
From: R-package-devel <r-package-devel-bounces using r-project.org> On Behalf Of Rolf Turner
Sent: 27 September 2022 02:38
To: Andrew Simmons <akwsimmo using gmail.com>
Cc: List r-package-devel <r-package-devel using r-project.org>
Subject: Re: [R-pkg-devel] Inquiry


On Mon, 26 Sep 2022 20:07:28 -0400
Andrew Simmons <akwsimmo using gmail.com> wrote:

> This issue isn't related to RStudio.
> 
> The issue is that you're exporting an object without providing any 
> documentation for it. It sounds like you don't want to export it, so 
> you need to go to your NAMESPACE file and remove the part was 
> export(r2). If you do want to export it, then you need to document it, 
> there's no way around that. The documentation doesn't need to be very 
> detailed.
> 
> 
> On Mon., Sep. 26, 2022, 20:01 , <teimouri using aut.ac.ir> wrote:
> 
> > ​Hi there,
> > I am writing to aks your help for an issuue arising when I am 
> > writing my R package using R studio 1.2.1335 as follows.
> > ``checking for missing documentation entries ... WARNING 
> > Undocumented code objects:
> >   'r2'
> > All user-level objects in a package should have documentation
> > entries." The function r2.r is among  .r   files within R folder of
> > my package. I am not interested to present "r2" in the R topics
> > documented: as a part of first page of built pdf help file of my 
> > package. I appreciate highly if you could help me to solve this 
> > issue.

My understanding is that functions, that are not meant to be called directly by users, should be documented in a file named <pkgnm>-internal.Rd.  It should have a structure something like:

> \name{pkgnm-internal}
> \alias{pkgnm-internal}
> \alias{foo}
> \alias{bar}
> \alias{clyde}
> \title{Internal pkgnm functions}
> \description{
>   Internal pkgnm functions.
> }
> \usage{
> foo(x,y,z)
> bar(melvin,irving,...)
> clyde(arrgh)
> }
> \details{
>   These functions are not intended to be called directly by the
>   user.  
> }
> \author{Hoo Hee
>   \email{hoo.hee using somewhere.otr}
> }
> \keyword{internal}

Then if someone types, e.g., "help(clyde)" they get the processed form of the forgoing *.Rd file displayed, and are thereby told that they probably should not mess with clyde().

cheers,

Rolf Turner

P.S. I always export everything.

R. T.

--
Honorary Research Fellow
Department of Statistics
University of Auckland
Phone: +64-9-373-7599 ext. 88276

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