Roxygen 7

[infotroph]

Description

First commit in this PR is just bumping Roxygen and recompiling docs:

git pull upstream develop
git switch -c roxygen-7
Rscript -e 'install.packages("roxygen2")'
make clean
make document

• **/DESCRIPTION: version bump in the RoxygenNote field, no other changes
• **/NAMESPACE: only modules/emulator changes, by now exporting S4 classes jump and mvjump. I see no problem with this, but someone who understands S4 classes better than me should double-check.
• */man*.Rd: Changes are mostly minor and obviously correct: line-wrapping, tweaks to translation between foo and \code{foo} vs \verb{foo}, better cross-package reference links, etc.Exceptions to the "obviously correct" rule are handled below.

I reviewed the above diff by hand, took notes on changes that looked wrong, then committed it and moved on to phase two. The remaining commits are me finding and resolving issues uncovered by the version change:

• Removed backslash escaping from percent signs inside Markdown text, because Roxygen now provides the escaping automatically. But beware: percents still need to be escaped in the packages that don't use Markdown (which is still most of them).
• Apparently the recommended way of providing whole-package documentation has changed slightly; I updated PEcAn.DB, the only one where it changed the result.
• ACTION NEEDED: When documenting multiple functions in the same Rd file, Roxygen used to include multiple copies of any function arguments that were specified multiple times. It now includes only one copy and ignores the others, even if they're worded differently. There were a few places it wasn't obvious how to resolve this; @ashiklom and @para2x, please see my comments below.
• Turns out PEcAn.data.atmosphere::met2CF.PalEONregional was defined twice, copy-paste identically, in the same file. Fixed that.
• Various small formatting / example / Roxygen syntax issues that weren't causing check errors before but started now. All needed fixing before too, the update just made them louder.

Motivation and Context

Review Time Estimate

• Immediately
• Within one week
• When possible

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My change requires a change to the documentation.
• I have updated the CHANGELOG.md.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[infotroph]

This file used to contain duplicate definitions for the parameters that are shared between sda.enkf and sda.enkf.original, but when rebuilt using Roxygen 7 it now only lists each parameter name once.

That seems desirable for functions documented in the same file, but note that where definitions differ only the one from sda.enkf is used (and the definitions from sda.enkf.original are not visible anywhere). @para2x please check carefully (the whole diff of this file, not just these lines I'm commenting at) and advise: Is that the correct result here?

[ashiklom]

I don't see any problems. Thanks for doing it! One less repository for which I need to hold back R package updates...

[robkooper]

only comment is the % that is escaped for latex I believe using %. Not sure if the pdf generation is smart enough for that.

[robkooper]

does this still work as expected with the pdf version. % is a latex char and I think that is why it was escaped.

[infotroph]

Seems to:

My understanding is that the PDF version is built from the Rd files without re-invoking Roxygen, and it's still spelled \% in the Rd file. this is just a switch from us typing it to Roxygen inserting it.