[R] Should I wrap more package examples in \dontrun{} ?

[Duncan Murdoch]

On 03/09/2013 1:02 PM, Yihui Xie wrote:
> But "don't use those packages that cause you trouble" implies you will
> have to reinvent and maintain all the wheels by yourself?

Isn't that a better alternative than having examples that don't work?
>
> What I do for long/complicated/time-consuming examples is I move them
> to package websites or separate repositories. For example, I started
> to use Vistat to show examples of the animation package (e.g. I write
> http://vis.supstat.com/2013/04/buffons-needle/ in the References in
> ?buffon.needle), and the knitr-examples repository
> (https://github.com/yihui/knitr-examples) to serve as both a testing
> repository and a learning repository. In these cases, it will reduce
> the check time on CRAN, and I'll know potential problems before CRAN's
> ticket comes. Of course, example(foo) won't show the long examples any
> more, but I believe it is worth it, since you gain more: you can make
> websites more visually pleasant than Rd (R documentation), you can
> show output so users do not really have to open R and run
> example(foo), and you have comments/interactivity/Google Analytics,
> etc... Rd is an excellent format for documenting function arguments
> and showing quick examples, though.

As a user, I'd rather have examples like the ones you are discussing 
above as vignettes in the package, so that I can use them while offline, 
and so that I can have some assurance that they are tested.  As a 
package author, I'm not so sure:  it is certainly more work to produce a 
vignette than to produce a web page, but the automatic testing is a good 
thing.  I don't like having my name on documents that give bad advice, 
and the CRAN checks detect some of that.

Duncan Murdoch
>
> Regards,
> Yihui
> --
> Yihui Xie <xieyihui at gmail.com>
> Web: http://yihui.name
> Department of Statistics, Iowa State University
> 2215 Snedecor Hall, Ames, IA
>
>
> On Tue, Sep 3, 2013 at 10:14 AM, Duncan Murdoch
> <murdoch.duncan at gmail.com> wrote:
> > On 03/09/2013 10:49 AM, Kevin Wright wrote:
> >>
> >> I have a package with more than 100 datasets, each of which has an
> >> \examples{} section.  On the plus side, these example test the "R
> >> ecosystem" to make sure that everything is working (both my package and
> >> others' packages).  On the down side, changes in this ecosystem have
> >> caused
> >> repeated NOTEs and WARNINGs from CRAN.
> >>
> >> As a commentary on one recent R-help discussion, none of the code
> >> breakages
> >> have been caused by use of ":::".  All of the problems have been caused by
> >> (1) Changes in "stable" packages and (2) changing CRAN requirements (3)
> >> changes in "beta" packages. In roughly that order.
> >>
> >> In the interest of long-term package stability I'm thinking about wrapping
> >> more of the examples in my package in \dontrun{}.  Especially the parts
> >> that depend on other packages.
> >>
> >> I'm interested to know how other package developers approach this problem.
> >>
> > As a user of your package, I would find it irritating if example(foo) didn't
> > run anything.   It would be more irritating (and would indicate sloppiness
> > on your part) if the examples failed when I cut and pasted them.  These both
> > suggest leaving the examples running.
> >
> > As the author of your package, it sounds as though you find it quite
> > irritating when other authors break your code.
> >
> > Isn't the right solution to this to work with the other package authors to
> > come up with code that is unlikely to break?  If that's not possible, then
> > maybe don't use those packages that cause you trouble.
> >
> > Duncan Murdoch