On Mon, Jun 30, 2014 at 6:19 AM, Duncan Murdoch <murdoch.dun...@gmail.com> wrote:
> 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. > > This is a good point. We could somehow add that message dynamically to the displayed help, or emit a message at the console. > >> 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. > > Probably just not having to redocument the symbol manually (i.e., passing check without a a warning, as there is now) will be a sufficient carrot. > Duncan > > >> Michael >> >> >> >> On Sun, Jun 29, 2014 at 12:43 PM, Duncan Murdoch < >> murdoch.dun...@gmail.com <mailto:murdoch.dun...@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 <x...@yihui.name >> <mailto:x...@yihui.name> >> > <mailto:x...@yihui.name <mailto:x...@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 <xieyi...@gmail.com <mailto:xieyi...@gmail.com> >> <mailto:xieyi...@gmail.com <mailto:xieyi...@gmail.com>>> >> >> > Web: http://yihui.name >> > >> > >> > On Fri, Jun 20, 2014 at 1:34 AM, Yihui Xie <x...@yihui.name >> <mailto:x...@yihui.name> >> > <mailto:x...@yihui.name <mailto:x...@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 <xieyi...@gmail.com <mailto:xieyi...@gmail.com> >> <mailto:xieyi...@gmail.com <mailto:xieyi...@gmail.com>>> >> >> > > Web: http://yihui.name >> > > >> > > >> > > On Fri, Jun 20, 2014 at 12:19 AM, Winston Chang >> > <winstoncha...@gmail.com <mailto:winstoncha...@gmail.com> >> <mailto:winstoncha...@gmail.com <mailto:winstoncha...@gmail.com>>> >> >> wrote: >> > >> On Thu, Jun 19, 2014 at 3:15 PM, Martyn Plummer >> <plumm...@iarc.fr <mailto:plumm...@iarc.fr> >> > <mailto:plumm...@iarc.fr <mailto:plumm...@iarc.fr>>> wrote: >> > >> >> > >>> Export filter in the NAMESPACE file *without copying >> it* in the >> > R source >> > >>> code. >> > >>> >> > >>> >> > >> Ah, it works! Thank you! >> > >> >> > >> > ______________________________________________ >> > R-devel@r-project.org <mailto:R-devel@r-project.org> >> <mailto:R-devel@r-project.org <mailto:R-devel@r-project.org>> >> mailing list >> > https://stat.ethz.ch/mailman/listinfo/r-devel >> > >> > >> >> >> > [[alternative HTML version deleted]] ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
