On 16.09.2010 20:18, Janko Thyson wrote:
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.
- I don't think package.skeleton overwrites files unless you ask for it.
- I think once you got started with your package, it is not required to
call package skeleton again. I tend to add files manually since I am
working on the package hierarchy itself using some editor...
- Last time I used package.skeleton is probably more than 2 years ago
(except for presentations in courses about package creation).
Best,
Uwe
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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
