On 31/01/2018 6:33 AM, Joris Meys wrote:
Dear Duncan,
With all respect, but I strongly disagree on your stance regarding
roxygen2 for multiple reasons:
1. It is in my humble opinion not correct to evaluate a tool based on
the abuse of some users. It's not because people write packages with bad
documentation, that roxygen2 is to blame. I use roxygen2, and I care a
great deal about documentation. So I actually took a bit offense there.
Sorry about that. I did say I wanted to be proven wrong.
2. Writing .Rd files directly means that you have to write out the usage
yourself, know the different tags needed for documenting different types
of generics and methods, and so forth.
Not at all --- that's what the prompt() function does.
It means a lot more iterations to
get every tag right so that R CMD check does not complain any more. It
requires a more detailed knowledge of the entire Rd tag system compared
to letting roxygen2 do the standard work for you. So one could argue
that the extra knowledge required would actually hinder starting
developers to write good documentation as opposed to help them.
New users (and old users) should use prompt() to set up the basic help page.
There are situations where prompt() doesn't help, namely edits to
existing pages:
- adding a second function.
- adding new parameters.
I think the infrastructure is there to allow functions to be written to
do these things, but as far as I know nobody has done it.
3. given your criticism, I'd like your opinion on where I can improve
the documentation of https://github.com/CenterForStatistics-UGent/pim.
I'm currently busy updating the help files for a next release on CRAN,
so your input is more than welcome.
Sure, I'll take a look.
I'm not going to force anyone to use roxygen2. But I personally find it
easier to have the function right below the documentation, so that any
change to the function can immediately be documented as well. You prefer
to do this by keeping that strictly separated, which is absolutely fine.
It's just not my prefered workflow. Different animal, different habits I
guess.
On a sidenote: I had a lot of complaints about earlier iterations of
roxygen2 and the many changes to tags and their meanings, but the
roxygen2 package matured in the meantime and has been a stable and
reliable tool for me the past years.
I formed my opinion several years ago, so perhaps I should take another
look. One problem is lock-in: once you write an Rd file, you can't (as
far as I know) easily import it as Roxygen markup. So I'd have to start
a new package to get experience with Roxygen. Maybe it should be the
package that adds the Rd tools mentioned above :-).
Duncan Murdoch
Kind regards
Joris
On Tue, Jan 30, 2018 at 8:53 PM, Duncan Murdoch
<murdoch.dun...@gmail.com <mailto:murdoch.dun...@gmail.com>> wrote:
On 30/01/2018 11:29 AM, Brian G. Peterson wrote:
On Tue, 2018-01-30 at 17:00 +0100, Suzen, Mehmet wrote:
Dear R developers,
I am wondering what are the best practices for developing an R
package. I am aware of Hadley Wickham's best practice
documentation/book (http://r-pkgs.had.co.nz/). I recall a
couple of
years ago there were some tools for generating a package out
of a
single file, such as using package.skeleton, but no
auto-generated
documentation. Do you know a way to generate documentation and a
package out of single R source file, or from an environment?
Mehmet,
This list is for development of the R language itself and closely
related tools. There is a separate list, R-pkg-devel, for
development
of packages.
Since you're here, I'll try to answer your question.
package.skeleton can create a package from all the R functions in a
specified environment. So if you load all the functions that
you want
in your new package into your R environment, then call
package.skeleton, you'll have a starting point.
At that point, I would probably recommend moving to RStudio, and
using
RStudio to generate markdown comments for roxygen for all your newly
created function files. Then you could finish off the
documentation by
writing it in these roxygen skeletons or copying and pasting from
comments in your original code files.
I'd agree about moving to RStudio, but I think Roxygen is the wrong
approach for documentation. package.skeleton() will have done the
boring mechanical part of setting up your .Rd files; all you have to
do is edit some content into them. (Use prompt() to add a new file
if you add a new function later, don't run package.skeleton() again.)
This isn't the fashionable point of view, but I think it is easier
to get good documentation that way than using Roxygen. (It's easier
to get bad documentation using Roxygen, but who wants that?)
The reason I think this is that good documentation requires work and
thought. You need to think about the markup that will get your
point across, you need to think about putting together good
examples, etc.
This is *harder* in Roxygen than if you are writing Rd files,
because Roxygen is a thin front end to produce Rd files from
comments in your .R files. To get good stuff in the help page, you
need just as much work as in writing the .Rd file directly, but then
you need to add another layer on top to put in in a comment. Most
people don't bother.
I don't know any packages with what I'd consider to be good
documentation that use Roxygen. It's just too easy to write minimal
documentation that passes checks, so Roxygen users don't keep
refining it.
(There are plenty of examples of packages that write bad
documentation directly to .Rd as well. I just don't know of
examples of packages with good documentation that use Roxygen.)
Based on my criticism last week of git and Github, I expect to be
called a grumpy old man for holding this point of view. I'd
actually like to be proven wrong. So to anyone who disagrees with
me: rather than just calling me names, how about some examples of
Roxygen-using packages that have good help pages with good
explanations, and good examples in them?
Back to Mehmet's question: I think Hadley's book is pretty good,
and I'd recommend most of it, just not the Roxygen part.
Duncan Murdoch
______________________________________________
R-devel@r-project.org <mailto:R-devel@r-project.org> mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
<https://stat.ethz.ch/mailman/listinfo/r-devel>
--
Joris Meys
Statistical consultant
Department of Data Analysis and Mathematical Modelling
Ghent University
Coupure Links 653, B-9000 Gent (Belgium)
<https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium&entry=gmail&source=g>
-----------
Biowiskundedagen 2017-2018
http://www.biowiskundedagen.ugent.be/
-------------------------------
Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
