create and store man/roxygen/templates

[kellijohnson-NOAA]

Do others think that it is a good idea to store man/roxygen/templates for things like @verbose in this repository. I am not sure how this would work in practice but in theory it seems good to me. I wonder if any other organizations share documentation across packages? @k-doering-NOAA have you ever seen this before? Also, could we just create a GitHub action that upon any changes to man/roxygen/templates files a pull request would be opened in downstream packages that updated the files used?

[k-doering-NOAA]

I wonder if Tidyverse does something like this.

[iantaylor-NOAA]

I just looked at some tidyverse roxygen documentation and they don't seem to use @template.
However, they extensively use @inheritParams (e.g., at https://github.com/tidyverse/dplyr/blob/main/R/pull.R#L7-L8)

This approach is documented in

• https://r-pkgs.org/man.html#inheriting-arguments and
• https://cran.r-project.org/web/packages/roxygen2/vignettes/reuse.html

However, the r-pkgs reference notes a possible problem with sharing documentation across packages:

You can inherit documentation from a function in another package by using the standard :: notation, i.e. @inheritParams anotherpackage::function. This does introduce one small annoyance: now the documentation for your package is no longer self-contained and the version of anotherpackage can affect the generated docs. Beware of spurious diffs introduced by contributors who run devtools::document() with a different installed version of the inherited-from package.

My preference would be for each package to have self-contained documentation. If we ever put all of the SS3-related R packages into this one organization then we could revisit the approach.
@kellijohnson-NOAA if you're OK with that approach, we could close this issue or transfer it to ss3sim or r4ss if you think it should remain available.

[kellijohnson-NOAA]

@iantaylor-NOAA I have started using @inheritParams in some of my coding rather than @template because {tidyverse} guidelines suggested it but I haven't converted everything over. I think we can close this issue once we tick both boxes

• open separate issues for {ss3sim} to suggest the use of @inheritParams
• open separate issue for {r4ss} to suggest the use of @inheritParams

[iantaylor-NOAA]

Issue added to r4ss and ss3sim
r4ss/r4ss#814
ss3sim/ss3sim#408