[Rd] Correct NAMESPACE approach when writing an S3 method for a generic in another package

[Martyn Plummer]

I think rgl should be in Depends.  You are providing a method for a
generic function from another package. In order to use your method, you
want the user to be able to call the generic function without scoping
(i.e. without calling rgl::plot3d), so the generic should be on the
search path, so the package that provides it should be listed in Depends
in the NAMESPACE file.

Martyn

On Fri, 2013-08-23 at 22:01 -0600, Gavin Simpson wrote:
> Dear List,
> 
> In one of my packages I have an S3 method for the plot3d generic
> function from package rgl. I am trying to streamline my Depends
> entries but don't know how to have
> 
> plot3d(foo)
> 
> in the examples section for the plot3d method in my package, without
> rgl being in Depends.
> 
> Note that I importFrom(rgl, plotd3d) and register my S3 method via
> S3Method() in the NAMESPACE.
> 
> If rgl is not in Depends but in Imports, I see this when checking the package
> 
> > ## 3D plot of data with curve superimposed
> > plot3d(aber.pc, abernethy2)
> Error: could not find function "plot3d"
> 
> I presume this is because rgl's namespace is only loaded but the
> package is not attached to the search path.
> 
> Writing R extensions indicates that one can export from a namespace
> something that was imported from another package namespace. I thought
> that might help the situation, and now the code doesn't raise an
> error, I get
> 
> * checking for missing documentation entries ... WARNING
> Undocumented code objects:
>   ‘plot3d’
> All user-level objects in a package should have documentation entries.
> See the chapter ‘Writing R documentation files’ in the ‘Writing R
> Extensions’ manual.
> 
> as I don't document plot3d() itself.
> 
> What is the recommended combination of Depends and Imports plus
> NAMESPACE directives etc that one should use in this situation? Or am
> I missing something else?
> 
> I have a similar issue with my package including an S3 method for a
> generic in the lattice package, so if possible I could get rid of both
> of these from Depends if I can solve the above issue.
> 
> Thanks in advance.
> 
> Gavin
>