On Thu, Feb 1, 2018 at 9:20 AM, Gabriel Becker <gmbec...@ucdavis.edu> wrote:
> 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. > > 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@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel > [[alternative HTML version deleted]] ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
