R devel - Feb 2018 - Best practices in developing package: From a single file

Joris,

With the large caveat that I am not Duncan, and thus am not speaking for
him, I can see an argument for his claim that I think is, more or less,
true.

roxygen2 (as far as I know as someone who uses it at least some of the
time) maps to only a subset of Rd. It is the most commonly used subset, and
so you can do most common things with it, but I think a pretty good case
can be made for the fact that it *actively discourages* the bits it doesn't
directly support. Ie doing things that would require you to put Rd syntax
into the roxygen comments. In as much as those aspects of Rd are required
for good documentation *in some cases*, in those cases, good documentation
is discouraged. Not disallowed, mind you - you CAN put the Rd syntax into
your roxygen comments and have it work - but discouraged.

There is also the case that I think Michael was alluding to, that in some
types of R software things that belong in the same help file are not
co-localized in R code. This is , again, supported by oxygen, of course,
but it removes one of the primary benefits of the system, i.e.
documentation-proximity-to-code.

Also, as I understood Duncan's comments, he was not saying good
documentation CANNOT be written in oxygen, just like good R code CAN be
written in notepad, rather than an IDE like RStudio or Emacs+ESS, but doing
so doesn't encourage the process.

All that said, at the end of the day, I generally agree with what Yehui
said as well. If you use roxygen2 and feel that it helps you to write good
documentation, great! Use it.  Thats ultimately not a statement about what
kind of documentation it encourages.

As a final thought, my personal view is that roxygen2 does not encourage
good or bad documentation, but rather middling documentation. It encourages
new users and those with major time or focus constraints to document things
more than they would without it, which is good, but doesn't encourage
really top notch documentation either and as with all things, hand-crafted
"artisanal" documentation will often be of higher quality.

Best,
~G

On Wed, Jan 31, 2018 at 8:35 AM, Suzen, Mehmet <suzen at acm.org> wrote:
> Dear Dr. Pfaff,
>
> Thank you for this, creating a package out of single file was my
> oriingal question, but not only creating and also maintaining it that
> way so R package is an artifact of the development process rather than
> "manually maintained" structure. I will have look at your
sources.
>
> Best,
>
> Mehmet S?zen
> <suzen at acm.org>
>
>
> On 31 January 2018 at 15:51, Pfaff, Bernhard Dr.
> <Bernhard_Pfaff at fra.invesco.com> wrote:
> > Dear All:
> >
> > stepping in late, but @Joris, if you would like to take 'from a
single
> file' literally,
> > have a look at:
> >
> >         https://github.com/bpfaff/lp4rp
> >
> > (lp4rp: literate programming for R packages);
> >
> > Cheers,
> > Bernhard
> >
> > ps:  incidentally, within the noweb-file roxygen is employed.
> >
> > -----Urspr?ngliche Nachricht-----
> > Von: R-devel [mailto:r-devel-bounces at r-project.org] Im Auftrag von
> Joris Meys
> > Gesendet: Mittwoch, 31. Januar 2018 14:02
> > An: Duncan Murdoch
> > Cc: r-devel
> > Betreff: [EXT] Re: [Rd] Best practices in developing package: From a
> single file
> >
> > On Wed, Jan 31, 2018 at 1:41 PM, Duncan Murdoch <
> murdoch.duncan at gmail.com>
> > wrote:
> >
> >> On 31/01/2018 6:33 AM, Joris Meys wrote:
> >>
> >> 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.
> >>>
> >>
> >> After this invitation I sent some private comments to Joris.  I
would
> >> say his package does a pretty good job of documentation; it
isn't the
> >> kind of Roxygen-using package that I was complaining about.  So I
will
> >> say I have received an example of a Roxygen-using package that has
> >> good help pages.
> >>
> >
> > Thank you for the nice compliment and the valuable tips.
> >
> > --
> > 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
> >
> >         [[alternative HTML version deleted]]
> >
> > ______________________________________________
> > R-devel at r-project.org mailing list
> > https://stat.ethz.ch/mailman/listinfo/r-devel
> > *****************************************************************
> > Confidentiality Note: The information contained in this
...{{dropped:10}}
> >
> > ______________________________________________
> > 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
>


-- 
Gabriel Becker, PhD
Scientist (Bioinformatics)
Genentech Research

	[[alternative HTML version deleted]]

On 31 janv. 2018, at 09:08, Gabriel Becker <gmbecker at ucdavis.edu>
wrote:
> it *actively discourages* the bits it doesn't directly support.
It may be discouraging to include Rd syntax in roxygen docs but only
because the LaTeX-like syntax of Rd is burdensome, not because of
roxygen. It is still handy to have inlined Rd as a backup and we do
use it for the cases where we need finer grained control.

I agree with your sentiment that roxygen encourages writing of
documentation for time-constrained users.

I'll add that the major problem of documentation is not fancy
formatting but the content getting out of sync with the codebase.
Having documentation sitting next to the code is the preferred
antidote to doc rot, e.g. docstrings in lisp languages, Julia and
Python, the Linux kernel-doc system, doxygen, javadoc, ...
It is true that R CMD check extensive checks help a lot as well in
this regard though only for things that can be checked automatically.

Best,
Lionel

On Thu, Feb 1, 2018 at 5:24 AM, Lionel Henry <lionel at rstudio.com>
wrote:
> On 31 janv. 2018, at 09:08, Gabriel Becker <gmbecker at ucdavis.edu>
wrote:
>
> > it *actively discourages* the bits it doesn't directly support.
>
> It may be discouraging to include Rd syntax in roxygen docs but only
> because the LaTeX-like syntax of Rd is burdensome, not because of
> roxygen. It is still handy to have inlined Rd as a backup and we do
> use it for the cases where we need finer grained control.
>
I only somewhat agree with this. Part of it is the Rd specifically, I
agree, but part of it is just the fact that it is a different syntax at
all. People who write roxygen documentation tend to think about and write
it in roxygen, I think. Any switch out to another syntax, thus introducing
two syntaxes side-by-side, is discouraged by the very fact that they are
thinking in roxygen comments.

Again, this is a "discouragement", not a disallowing. I know that
people
who care deeply about writing absolutely top notch documentation, and who
also use roxygen will do the switch when called for, but the path of least
resistance, i.e. the pattern of behavior that is *encouraged* by roxygen2
is to not do that, and simply write documentation using only the supported
roxygen2 tags. I'm not saying this makes the system bad, per se. As I
pointed out, I use it in many of my packages (and it was my choice to do
so, not because I inherited code from someone who already did), but
pretending it doesn't encourage certain types of behavior doesn't seem
like
the right way to go either.

>
> I agree with your sentiment that roxygen encourages writing of
> documentation for time-constrained users.
>
I do think it does that, but that was really only half of what I said, I
said it encourages time constrained users to write middling (i.e. not
great) documentation. Another person pointed out that structurally it
really encourages terseness in the explanations of parameters, which I
think is very true and have heard independently from others when talking
about it as well. This is again not a requirement, but it is a real thing.

>
> I'll add that the major problem of documentation is not fancy
> formatting but the content getting out of sync with the codebase.
> Having documentation sitting next to the code is the preferred
> antidote to doc rot, e.g. docstrings in lisp languages, Julia and
> Python, the Linux kernel-doc system, doxygen, javadoc, ...
>
I mean, it is *an *antidote to doc rot. And sure, one that is used
elsewhere. You could easily imagine one that didn't require it though.
Perhaps doc files associated with objects (including closures) could embed
a hash of the object they document, then you could see which things have
changed since the documentation was updated and look at which documentation
is still ok and which needs updating. That's just off the top of my head,
I'm sure you could make the detection much more sophisticated.

Or perhaps you could imagine two help systems, akin to --help and man for
command line tools, one of which is minimalist showing usage, etc,
generated by roxygen comments, and one of which is much more extensive, and
not tied to (what could be extremely large) comments in the same .R file as
the code.

Best,
~G

> It is true that R CMD check extensive checks help a lot as well in
> this regard though only for things that can be checked automatically.
>
> Best,
> Lionel
>
>

-- 
Gabriel Becker, PhD
Scientist (Bioinformatics)
Genentech Research

	[[alternative HTML version deleted]]