[Rd] a small suggestion for improving the building of packages

[William Dunlap]

> From: r-devel-bounces at r-project.org 
> [mailto:r-devel-bounces at r-project.org] On Behalf Of Janko Thyson
> Sent: Thursday, September 16, 2010 11:19 AM
> To: r-devel at r-project. org
> Subject: Re: [Rd] a small suggestion for improving the 
> building of packages
...
> Dear Uwe, 
> in principle, I totally agree with your point of politely 
> forcing developers
> to write well documented packages. However, when you're trying to put
> together a package, you (or at least I) never get it 
> completely right on the
> first, say, 20 tries ;-) Yet, by running package.skelleton() 
> over and over
> to keep track of changes you made during the process, you 
> overwrite all Rd
> files each time - including the ones that you might already 
> have put a lot
> of effort into. 

Running package.skeleton more than once is destructive.
Perhaps it needs an update=TRUE/FALSE sort of option
to let you add functions and Rd templates.

When I start a package I don't use package.skeleton,
mainly because it won't make all the usual directories
that I expect to eventually use: src, data, inst, test
(or it is tests?), etc.  I'd rather that it made all
the usual directories (with the proper spelling) so
I could delete them if they ended up being empty.
Do other package writers use package.skeleton routinely?

I copy a template package directory, edit the template
DESCRIPTION file, copy my code into the appropriate
subdirectories, and run prompt(func, filename="pkg/man/func.Rd")
on each function or dataset.   The last step is a pain:
it would be nice if prompt had a dir= or destdir= argument
so that
   prompt(func, destdir="pkg/man")
would make the file "pkg/man/func.Rd".

Bill Dunlap
Spotfire, TIBCO Software
wdunlap tibco.com 

> And delaying documentation to the very end of 
> the process is
> probably not the best idea either ;-) IMHO the community 
> should favor the
> approaches taken by packages such as roxygen or inlinedocs as 
> at least it
> provides some sort of direct synchronization between code and 
> documentation.
> Maybe one could agree on rejecting code that is missing 
> roxygen or inlinedoc
> code, which would ensure that code is documented properly. In 
> fact, isn't
> programming all about automating unnecessary manual 
> procedures? I would
> count starting from scratch with all help files time and time 
> again to be
> one of those unnecessary procedures. This time could better 
> be invested in
> increasing the package's functionality.
> 
> Best regards, my thanks go out to everyone as well,
> Janko
> 
> > > Thanks, as always, to everyone for their hard work to keep my
> > statistical
> > > computing free and easy.
> > >
> > > Best,
> > >
> > > Kyle
> > >
> > > [[alternative HTML version deleted]]
> > >
> > > ______________________________________________
> > > R-devel_at_r-project.org mailing list
> > > https://stat.ethz.ch/mailman/listinfo/r-devel
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>