[Rd] ‘:::’ call

[Duncan Murdoch]

On 28/08/2013 2:50 PM, Paul Gilbert wrote:
> On 13-08-28 12:29 PM, Marc Schwartz wrote:
> >
> > On Aug 28, 2013, at 11:15 AM, Paul Gilbert <pgilbert902 at gmail.com> wrote:
> >
> >> I have a package (TSdbi) which provides end user functions that I export, and several utilities for plugin packages (e.g. TSMySQL) that I do not export because I do not intend them to be exposed to end users. I call these from the plugin packages using TSdbi:::  but that now produces a note in the checks:
> >>
> >> * checking dependencies in R code ... NOTE
> >> Namespace imported from by a ‘:::’ call: ‘TSdbi’
> >>   See the note in ?`:::` about the use of this operator. :: should be
> >>   used rather than ::: if the function is exported, and a package
> >>   almost never needs to use ::: for its own functions.
> >>
> >> Is there a preferred method to accomplish this in a way that does not produce a note?
> >>
> >> Thanks,
> >> Paul
> >
> >
> >
> > Paul,
> >
> > See this rather lengthy discussion that occurred within the past week:
> >
> >    https://stat.ethz.ch/pipermail/r-devel/2013-August/067180.html
> >
> > Regards,
> >
> > Marc Schwartz
>
> I did follow the recent discussion, but no one answered the question "Is
> there a preferred method to accomplish this?" (I suppose the answer is
> that there is no other way, given that no one actually suggested
> anything else.) Most of the on topic discussion in that thread was about
> how to subvert the CRAN checks, which is not what I am trying to do and
> was also pointed out as a bad idea by Duncan. The substantive response was
>
>   >r63654 has fixed this particular issue, and R-devel will no longer
>   >warn against the use of ::: on packages of the same maintainer.
>   >
>   >Regards,
>   >Yihui
>
> but that strikes me as a temporary work around rather than a real
> solution: suppose plugins are provided by a package from another maintainer.
>
> Since CRAN notes have a habit of becoming warnings and then errors, it
> seems useful to identify the preferred legitimate approach while this is
> still a note. That would save work for both package developers and CRAN
> maintainers.
>
> My thinking is that there is a need for a NAMESPACE directive something
> like limitedExport() that allows ::: for identified functions without
> provoking a CRAN complaint when packages use those functions. But there
> may already be a better way I don't know about. Or perhaps the solution
> is to split the end user functions and the utilities for plugin packages
> into two separate packages?

I don't see a need for that.  The reason ::: is bad is because 
non-exported functions may change without notice, breaking the package 
that uses them, and possibly giving the users of that package bad 
results.  If you're the maintainer of both the donor and user of the 
non-exported function, then you can be expected to keep them in sync, 
hence r63654.  If those are different people, then the donor had better 
indicate that the function is safe to use.  That's what export() does.

If you are worried about a cluttered listing of functions and help 
pages, you can use an initial "." in the name of the object, or use 
\keyword{internal} in the .Rd file.  I forget the full list of effects 
of each of these, but using both should make your function nearly 
invisible, while still exported if it is listed as such in the NAMESPACE 
file.

Duncan Murdoch