[Rd] ‘:::’ call

[Paul Gilbert]

I may have confused things by referring to ':::' which everyone reads as 
not exported, not documented, not part of the API, constantly changing, ...

In my mind, the real question is about two levels of exporting, one to 
other package developers, and another to end users. In both cases they 
are part of the "API", relatively constant, and documented. (I try to 
document even internal functions, otherwise I can't remember what they do.)

So far, I see three possible solutions:

   1/ R adds another namespace directive allowing certain functions to 
be "exported" differently, possibly just by causing the checks to be 
silent about ::: when those functions are used in that way by other 
packages.

  2/ The package gets split in two, one for use by other packages and 
one for use by end users.

  3/ Some functions are exported normally but hidden by using "." in the 
beginning of their names. Other package maintainers would know they 
exist, but end users would not so easily find them. (Duncan's other 
suggestion of using \keyword{internal} in the .Rd file strikes me as 
problematic. I'm surprised CRAN checks do not already object to 
functions exported and documented with \keyword{internal}.)

Paul

On 13-08-28 03:44 PM, Yihui Xie wrote:
> If this issue is going to be solved at all, it might end up as yet
> another "hack" like utils::globalVariables just to "fix" R CMD check
> which was trying to fix things that were not necessarily broken.
>
> To be clear, I was not suggesting subvert this check. What I was
> hoping is a way to tell CRAN that "Yes, I have read the documentation;
> I understand the risk, and I want to take it like a moth flying into
> the flames".
>
> Many people have been talking about this "risk", and how about some
> evidence? Who was bitten by :::? How many real cases in which a
> package was broken by :::?
>
> Yes, unexported functions may change, so are exported functions (they
> may change API, be deprecated, add new arguments, change defaults, and
> so on). Almost everything in a package is constantly evolving, and I
> believe the correct way (and the only way) to stop things from being
> broken is to write enough test cases. When something is broken, we
> will be able to know that. Yes, we may not have control over other
> people's packages, but we always have control over our own test cases.
> IMHO, testing is the justification of CRAN's reputation and quality,
> and that is a part of what CRAN does.
>
> In God we trust, and everyone else should bring tests.
>
> Regards,
> Yihui
> --
> Yihui Xie <xieyihui at gmail.com>
> Web: http://yihui.name
> Department of Statistics, Iowa State University
> 2215 Snedecor Hall, Ames, IA
>
>
> On Wed, Aug 28, 2013 at 1:50 PM, Paul Gilbert <pgilbert902 at gmail.com> 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?
>>
>> Paul