[Rd] legitimate use of :::

[Duncan Murdoch]

On 26/08/2013 8:51 AM, Benjamin Hofner wrote:
> Hi,
>
> related to this important discussion I have several questions:
>
> What can I do to explicitly state that I want to use a certain,
> *non-exported* generic function? The function I am currently talking of
> is predict.smooth.spline from package stats. As I want to make shure
> that *this* function is used I currently call
> stats:::predict.smooth.spline() in my code, which now triggers a NOTE on
> CRAN. Strange enough predict.smooth.spline even has a manual page but is
> not exported (as is true for many other generic functions as well).

Actually the standard name is that predict() is a generic function, 
predict.smooth.spline() is a method, but it's a good question.  Can you 
describe why you want to call that method on something that isn't a 
smooth.spline object?
>
> Is it advisable to specify (S3) methods without exporting them? How can
> I access exactly this function without using :::? And/or shouldn't we (R
> Core in this instance but others - including myself) export all methods
> (especially if a manual exists anyway)?

The general reason for hiding methods is that it allows the author of the package to change the internal implementation of the class without worrying that it will break code that uses the method, i.e. it will stop usages such as yours.  So you need to explain why you are doing what you are doing.


> A related question concerns the function stats:::n.knots. I want to use
> this function to compute the number of knots for a spline (not
> necessarily a smoothing spline as defined by smooth.spline were it is
> originally used). The source of the function even states as a comment:
> "## Namespace-hidden but at least available to programmeRs:" So I guess
> this function can be considered to be stable and usable. Would it then
> be possible for R Core to export this function?
>
> Finally, if one needs to copy a function (perhaps with minor
> modifications), how does one properly state the authorship of the code
> that one copies? Are there any guidelines, rules, ...? Is it sufficient
> for small functions to state the original authorship as a comment in the
> source? Is it necessary to state the authorship in the manual? Or is it
> even required to state the quthorship in the DESCRITPION? I already did
> an extensive search of the R-devel mailing list but couldn't find an
> appropriate answer. And after all I do not want to spend hours and hours
> thinking about licenses, authorship etc. but I want to produce nice and
> usable code (but also want to mention the original authors appropriately)!

I would say that you should certainly state it in the man page, and have 
something in the DESCRIPTION file as well.  It might be something like

Author:  Duncan Murdoch, with code from others (see the man pages)

However, I just looked at rgl (a package I maintain), and I see we 
didn't do that.  We have a separate README file listing other credits.

Duncan Murdoch

>
> Happy to learn more and read your thoughts and ideas about these issues.
>
> All the best,
> Benjamin
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel