On Thu, Feb 1, 2018 at 5:24 AM, Lionel Henry <lio...@rstudio.com> wrote:
> On 31 janv. 2018, at 09:08, Gabriel Becker <gmbec...@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]] ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel