[Rd] R CMD check warning with S3 method
Duncan Murdoch
murdoch.duncan at gmail.com
Mon Jun 30 15:19:20 CEST 2014
On 30/06/2014 8:51 AM, Michael Lawrence wrote:
> I think it's generally nice to be able to compute on the network of
> imported and exported symbols, and exportFrom() preserves the
> information that a symbol has been forwarded. But let's focus on the
> use case of documenting the symbol.
>
> First, from the user perspective: my understanding (without testing
> anything) is that with promptImport(), the call to help() will find
> two or more hits to the symbol, so the user has to choose from a menu
> or otherwise qualify the package.
It depends how the user formulates it. The usual ?foo will find at
least two hits. But if a user qualifies it by saying ?pkg::foo,
they'll just get the redirect page.
I think we need ?pkg::foo to do something, and this seemed easier than
inventing an invisible redirect.
> Choosing the man page for the re-exported symbol will bring up a page
> that just requests them to make an extra click. This seems like extra
> work for the user. One potential benefit is that the user will know
> that a re-export has occurred, but does the user care? Why not proceed
> directly to the actual documentation? The majority of users have no or
> little knowledge of namespaces.
I think some users would like to know that pkg::foo is identical to
original::foo, so if we had the invisible redirect, I think the target
page should be modified to say "redirected from ...", just so the users
were sure they had come to the right place.
>
> From the developer perspective, promptImport() means that there is
> another man page to worry about, while exportFrom() would make it
> clear to developers reading the NAMESPACE that symbols are being
> simply forwarded, rather than re-defined.
Those are both benefits of your approach, which I wouldn't object to if
you go ahead and do it subject to the qualifications above, and one
other. How should existing redirects be handled? If a package imports
and re-exports a symbol without change, should the author be
encouraged/required to use exportFrom? If we do nothing, most people
will just do what they're currently doing, so maybe some sort of nag
should be added. Package writers won't like that unless there's some
obvious benefit to the change.
Duncan
>
> Michael
>
>
> On Sun, Jun 29, 2014 at 12:43 PM, Duncan Murdoch
> <murdoch.duncan at gmail.com <mailto:murdoch.duncan at gmail.com>> wrote:
>
> On 29/06/2014, 3:07 PM, Michael Lawrence wrote:
> > While the change to the symbol lookup is generally useful (e.g., for
> > finding S4 methods that become available whenever a package is
> loaded),
> > it seems that we ultimately want a mechanism by which a package
> > namespace can formally declare that it is re-exporting a symbol from
> > some package. Then, for example, the check mechanism can be made
> smart
> > enough to avoid throwing such warnings.
> >
> > I've developed a proof-of-concept exportFrom() namespace
> directive. This
> > is the syntax:
> >
> > exportFrom(utils, help)
> >
> > Then:
> >
> >> getNamespaceInfo("ReexportingPackage", "exports")$help
> > [1] "help"
> > attr(,"origin")
> > [1] "utils"
> >
> > Comments?
>
> I don't see why this is needed. What does it gain over
> documenting that
> the symbol "help" is just a copy of the one from utils? As of this
> morning, that's easy...
>
> Duncan Murdoch
>
> >
> > Michael
> >
> >
> > On Fri, Jun 27, 2014 at 8:32 PM, Yihui Xie <xie at yihui.name
> <mailto:xie at yihui.name>
> > <mailto:xie at yihui.name <mailto:xie at yihui.name>>> wrote:
> >
> > Hi Duncan,
> >
> > Again, thanks a lot for making this change (help requests
> are tried
> > over all loaded instead of attached packages):
> > https://github.com/wch/r-source/commit/21d2f7430b4 This makes what I
> > proposed last time possible now: if pkg B imports FUN from A and
> > re-exports it, ?FUN will work after B is attached because A
> will also
> > be at least attached.
> >
> > Then it will be perfect if `R CMD check` can stop warning
> against the
> > missing documentation, which is not really missing.
> >
> > Regards,
> > Yihui
> > --
> > Yihui Xie <xieyihui at gmail.com <mailto:xieyihui at gmail.com>
> <mailto:xieyihui at gmail.com <mailto:xieyihui at gmail.com>>>
> > Web: http://yihui.name
> >
> >
> > On Fri, Jun 20, 2014 at 1:34 AM, Yihui Xie <xie at yihui.name
> <mailto:xie at yihui.name>
> > <mailto:xie at yihui.name <mailto:xie at yihui.name>>> wrote:
> > > but note that you will have to document it even if it is a
> function
> > > imported from another package... Perhaps help() should be
> intelligent
> > > enough to link the documentation of `FUN` from package A
> for package B
> > > when B imports `FUN` from A, and exports it in B's
> NAMESPACE. The
> > > package name of A may be obtained from
> > > environmentName(environment(FUN)). At the moment, since R
> CMD check
> > > will warn against the missing documentation of `FUN` in B,
> I have to
> > > copy FUN.Rd from A to B in this case, which seems to be
> inefficient
> > > and not a best way to maintain. Did I miss anything in the
> R-exts
> > > manual?
> > >
> > > Regards,
> > > Yihui
> > > --
> > > Yihui Xie <xieyihui at gmail.com <mailto:xieyihui at gmail.com>
> <mailto:xieyihui at gmail.com <mailto:xieyihui at gmail.com>>>
> > > Web: http://yihui.name
> > >
> > >
> > > On Fri, Jun 20, 2014 at 12:19 AM, Winston Chang
> > <winstonchang1 at gmail.com <mailto:winstonchang1 at gmail.com>
> <mailto:winstonchang1 at gmail.com <mailto:winstonchang1 at gmail.com>>>
> wrote:
> > >> On Thu, Jun 19, 2014 at 3:15 PM, Martyn Plummer
> <plummerm at iarc.fr <mailto:plummerm at iarc.fr>
> > <mailto:plummerm at iarc.fr <mailto:plummerm at iarc.fr>>> wrote:
> > >>
> > >>> Export filter in the NAMESPACE file *without copying
> it* in the
> > R source
> > >>> code.
> > >>>
> > >>>
> > >> Ah, it works! Thank you!
> > >>
> >
> > ______________________________________________
> > R-devel at r-project.org <mailto:R-devel at r-project.org>
> <mailto:R-devel at r-project.org <mailto:R-devel at r-project.org>>
> mailing list
> > https://stat.ethz.ch/mailman/listinfo/r-devel
> >
> >
>
>
More information about the R-devel
mailing list