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

Best practices in developing package: From a single file

Thread (25 messages)