Improvement suggestion: remove version dependent message from roxygen generated documentation

[lucacerone]

I think it would be better to remove the version number from the documentation generated by roxygen2.

When collaborating to a package people can have different version of roxygen2 installed and git (or any other VCS) sees as modified a lot of documentation files just because the roxygen2 version is different.

Can the message be made version neutral?

[Geoff99]

Hi Luca. See the discussion under #334. :-)

Geoff

[hadley]

I think it's important that somewhere in the package includes the current version of roxygen - that makes it much easier to diagnose documentation difference when multiple people are working on the same package. But I agree that putting it in every file is overkill, and it only needs to be listed in one place. There are a few options for where that one place might be:

• in the DESCRIPTION
• in a special .Rd file (maybe the the package docs if it exists)
• in a special file elsewhere (would need to be automatically added to .Rbuildignore)

@gaborcsardi, @krlmlr do you have any thoughts?

[hadley]

If we were to make a dummy .Rd file, I think this is the smallest it could be:

\name{roxygen_version}
\title{Roxygen}
\description{4.1.0}
\keyword{internal}

[gaborcsardi]

The problem with this approach is that in fact different Rd files file might have been generated with different versions of roxygen, and your dummy file will contain one version only.

Or you would re-generate all files for each document() call? That generates some bloated commits, potentially, and you could still get a mixture of roxygen versions in the end, if people only commit the files that really changed.

I think the "correct" solution is to generate the docs at build time, but I know that you don't want to do that, and it is not really possible currently, anyway. Btw. having roxygen generate the docs without recompiling the package would be a step in this direction. Then you could roxygenize on the user's machine, without having to have a compiler there.

So, I think the current solution of having the header in each file is not too bad, actually.

[krlmlr]

I see two major issues here:

1. Documentation can be inconsistent with source
   • We could check this in a testthat test, and allow only pull requests that have properly updated documentation
2. Different installed version
   • Why not take the mountain to the prophet: devtools::document could look up the version of roxygen to use, and install it (if it's not yet available) to a temporary library

For myself, I am very comfortable with gitflow. This allows generating documentation at release time (which is something between development and build time). There is a CLI, which supports a set of hooks. A rough summary:

• There are two branches, "develop" and "master".
• The "develop" branch doesn't contain the redundant documentation (the man directory is removed), it is only present in the "master" branch.
• A helper package takes care of turning documentation on and off
  • off: the man directory is added to .gitignore, all files below man are removed
  • on: the man directory is removed from .gitignore, document() is run
• install_github for the develop branch works because that helper package also adds a small file that will magically create the man directory during R CMD INSTALL (and also devtools::load_all()).
• The release process is automated with gitflow hooks

This process is not tied to gitflow, but works well with it.

Advantages:

• Smaller pull requests, less Git clutter
• Contributors' roxygen version doesn't matter
• Process is opaque to contributors
• Full history of documentation in .Rd format (in the "master" branch)

Disadvantages:

• Need to maintain (and communicate) two Git branches
• Some infrastructure is required to make this process seamless for the maintainer

An example that uses this technique right from the start: https://github.com/krlmlr/import.gen

[hadley]

@gaborcsardi every call to document() re-documents every file, so I don't think you'd easily get versions that were out of sync.

[gaborcsardi]

@hadley I see. Then my only complaint about the current behaviour is the "developers with different roxygen versions" case, which is not easy to fix.

So again, considering the alternatives, I don't think the current behavior is too bad. Having a separate dummy file is fine, too, but probably there will be some "transition issues" if you put it in a file that is not ignored by R CMD build by default.

Btw. how about putting it in DESCRIPTION, in a RoxygenNote field? That's a valid field AFAIK.

[hadley]

Problem with non-standard field is that R CMD check warns about it :/

[gaborcsardi]

I don't think so. Here are the valid fields:
https://github.com/wch/r-source/blob/d992ae73fe794f72509500b09a561134bb9384ea/src/library/tools/R/utils.R#L1051

and here they allow everything that looks like <valid-field>Note:
https://github.com/wch/r-source/blob/d992ae73fe794f72509500b09a561134bb9384ea/src/library/tools/R/QC.R#L6613

Just tried it with 3.2.1, RoxygenNote is fine.

[krlmlr]

To the initial question: One possible answer might be packrat/packrat.lock. (This would work best if packrat supported an opt-in strategy, rstudio/packrat#64.) Other than that, RoxygenNote in DESCRIPTION looks like a good place -- is it likely that R-core decides to flag those fields at some point?

Do we have a testthat expectation that checks if documentation is up to date?

[hadley]

Ok, RoxygenNote looks good, and I think it's a compromise that will make the maximum number of people as happy as possible.

[gaborcsardi]

👍