Missing docs for archive.R

[dajmcdon]

I think the documentation on main was behind. I just updated and force pushed. But I got a slew of warnings for undocumented R6 methods and functions in archive.R. Do we need to add those?

[brookslogan]

Yes, we should probably add these. I think they are just a bunch of missing @param tags on the R6 methods. We should add these and have each R6 @param point to the non-R6 functions for the docs (with actual links, e.g.,

@param param same as in [`epix_fn_name`]

since we have markdown enabled.)

I recently messed around trying to look for a better way to share docs between the R6 and non-R6 versions of functions, but I think the approach above will be simpler, easier to catch doc bugs, and maybe even favorable on the reader's side. It's tricky because currently, a lot of roxygen tags don't work on R6 methods, and instead end up ignored or place output in the wrong spot. The only thing I could get working:

• We can share some R6 method and non-R6 docs for the params, a bit awkwardly. In the roxygen comments in the first block for the R6 class (not the method), we can use @template and even take advantage of @templateVar to clarify between self and x. But only when there is no overlap in parameter names among all the methods, or if there is overlap, we're okay with having identical documentation for all instances of that param. (@inheritParams might also work, but doesn't allow @templateVar, and makes accidental name overlap more likely if it does work.) But then we have to look up to the R6 initial class documentation block to see what params have been documented by looking at the templates, and maybe even look within the templates to see what params they cover. And when "reading" the non-R6 doc, we have to look at the non-param doc in one file, then jump to one/more template files to look at their docs. Not all that convenient, and it makes it easier to overlook doc bugs.

[brookslogan]

Tagged as P2 because while it seems pretty minor, it also may make use overlook actual issues with the R6 documentation. Also the approach I suggested above is pretty easy to implement.

The complaints should appear as "warnings" in devtools::check(vignettes=FALSE), but aren't tallied with the rest of the notes, warnings, and errors; they just appear somewhere in the console output. The fix is to add the missing @param documentation for the R6 methods, something along the lines of

@param x same as in [`epix_wrapper_fn_name_for_this_method`]

(The epix_wrapper_fn_name_for_this_method function should already have been implemented, in methods-epi_archive.R.)