[R] Explore roxygen2 R6 class documentation

[asfimport]

roxygen2 version 7.0 adds support for documenting R6 classes, rather than the ad hoc approach we've had to take without it: https://github.com/r-lib/roxygen2/blob/master/vignettes/rd.Rmd#L203

Try it out and see how we like it, and consider refactoring the docs to use it everywhere.

Reporter: Neal Richardson / @nealrichardson

_{Note: This issue was originally created as ARROW-6792. Please see the migration documentation for further details.}

[asfimport]

Neal Richardson / @nealrichardson:
I took a look at this in the course of writing documentation for ARROW-6340. Some observations:

• It's all or nothing. If we use the new roxygen at all, we have to update all of our existing docs. In that PR I added r6 = FALSE to the RoxygenNote to keep the old behavior for now.
• The first disqualifying feature I noticed is the that the new R6 stuff doesn't like how we documented several classes in the same file. It just repeats "Super classes" and "Methods" sections down the page. See Documenting multiple R6 (sub)classes in same file r-lib/roxygen2#961.
• Bad crossreferences (reported https://github.com/r-lib/pkgdown/issues/1177)