[Rd] Best practices in developing package: From a single file

[Lionel Henry]

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