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

[Janko Thyson]

> From: Uwe Ligges <ligges_at_statistik.tu-dortmund.de>
> Date: Wed, 15 Sep 2010 15:23:01 +0200
> On 29.08.2010 22:34, Kyle Matoba wrote:
> > All,
> >
> > I just finished the process of build a package for the first time and
> found
> > it characteristically (for R) very straightforward and well
> documented.
> >
> > Whenever I deal with open source software I always endeavor to finish
> the
> > task I have in mind, and upon completing this, I then revisit all of
> the
> > configurations, customizing as necessary to achieve my goals more
> fully.
> > The ability to achieve some minimal level of functionality without
> the
> need
> > for much filling in of configuration files, etc., is, I feel,
> important to
> 
> > not scaring off the less technically inclined such as myself.
> >
> > Based on this heuristic, it is my understanding that a few small
> suggestions
> > could make building a warning-free package as easy as running
> > package.skeleton(), then R CMD check, R CMD build:
> >
> > - Fill in default titles for each of the '*.Rd' files in /man
> > - Take out the tildes in the 'examples' section of the '*-package.Rd'
> main
> 
> > documentation file for the package (it seems to confuse the latex
> compiler)
> > - Put the lines '~~ Optionally other standard keywords, one per line,
> from
> 
> > file KEYWORDS in ~~
> > ~~ the R documentation directory ~~' into the \references{} section,
> there
> 
> > is presently a warning about all text needing to be in a section.
> Dear Kyle,
> thanks for the suggestions. Actually, it is intended to generate
> warnings /
> Errors in R CMD check: We want to force package developers to document
> their
> packages probably. This way, package maintainers / developers have to
> touch
> each Rd file and cannot use them as is in order to pass the checks.
> Best wishes,
> uwe

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. 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