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

[Michael Lawrence]

On Thu, Feb 1, 2018 at 9:20 AM, Gabriel Becker <gmbecker at ucdavis.edu> wrote:

> 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.
>
>
This is basically what I meant by the template-based approach. Have the
details in the template, and the vitals in the doc comment block. Combine
the two and view the docs in different ways, dynamically.


> 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]]
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

	[[alternative HTML version deleted]]