Migrate all MARSS docs to Roxygen2 (bulk .Rd → Roxygen2 conversion)

[Copilot]

Migrates hand-written .Rd documentation files in man/ to inline Roxygen2 comment blocks in their corresponding R/*.R files, then deletes the original .Rd files. The preview files from the initial single-file test have been removed.

Documentation migration

Each .Rd file is fully translated to a Roxygen2 block inserted directly before the corresponding function definition. Key conversion rules applied throughout:

• \usage{} blocks omitted — auto-generated by Roxygen2
• All .Rd markup converted to Roxygen2 Markdown (\strong{} → **text**, \emph{} → *text*, \code{} → `text`)
• \eqn{}{}/\deqn{}{} math macros preserved exactly (not converted to $/$$)
• Roxygen: list(markdown = TRUE) respected throughout — blank #' lines added between paragraphs to prevent line concatenation; lists use * item markdown syntax
• \keyword{internal} → @keywords internal (no @export); otherwise @export added
• Nested \describe{\item{}{}} blocks inside @param descriptions → indented markdown bullet lists
• \value{\item{name}{desc}} → @return with * name: desc bullet lists

Completed batches (30 of ~73 files):

Batch 1 — CSEGtmufigure, MARSS, MARSSFisherI, MARSS_dfa, MARSS_marss, MARSS_marxss, MARSSaic, MARSSapplynames

Batch 2 — MARSSboot, MARSSharveyobsFI, MARSShatyt, MARSShessian, MARSShessian_numerical, MARSSinfo, MARSSinits, MARSSkem, MARSSkemcheck

Batch 3 — MARSSinnovationsboot, stdInnov, MARSSkf, MARSSoptim, MARSSparamCIs, MARSSresiduals, MARSSresiduals_tT, MARSSresiduals_tt1, MARSSresiduals_ttt, MARSSsimulate, MARSSvectorizeparam

Remaining (in progress):

• Batch 4: accuracy_marssMLE, checkMARSSInputs, checkModelList, coef_marssMLE, describe_marssMODEL, fitted_marssMLE, forecast_marssMLE, glance_marssMLE, is_marssMLE, is_marssMODEL, logLik_marssMLE, model_frame_marssMODEL
• Batch 5: plot_, predict_, print_*, residuals, summary, tidy, toLatex, tsSmooth
• Batch 6 (special): utility functions, dataset docs, class docs, package-level docs, MARSS_vectorized, as_marssMODEL
• Final: R CMD Rd2pdf . --output=MARSS_Manual.pdf

Notes

• MARSScv.Rd and MARSSfit.Rd were already auto-generated from existing Roxygen2 sources (R/MARSScv.R and R/MARSS-methods.R) and are left as-is
• The CSEGriskfigure_preview.html and CSEGriskfigure_preview.pdf files used during initial testing have been removed from the branch

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Convert man/CSEGriskfigure.Rd to a Roxygen2 Markdown header in `R/CSEGriskfigure.R</issue_title>
<issue_description>Description:

I am migrating the documentation for this package to Roxygen2. I am starting with a single file to test the workflow.

Your task is to read the existing manual file man/CSEGriskfigure.Rd and translate its contents entirely into a Roxygen2 comment block (#'). You will insert this Roxygen2 block at the very top of R/CSEGriskfigure.R and then delete the original .Rd file.

CRITICAL CONSTRAINTS:

1. DO NOT read or analyze the R code to generate documentation. You must rely strictly on the text provided in the .Rd file. Do not invent, infer, or summarize anything.
2. Complete Translation: The resulting Roxygen header must contain everything from the .Rd file, with the sole exception of the \usage{...} block. Ignore the \usage{...} block entirely; Roxygen2 will generate this automatically.
3. Markdown Syntax: You must translate standard .Rd formatting into Roxygen2 Markdown:
   • \strong{text} -> **text**
   • \emph{text} -> *text*
   • \code{text} -> `text`

Mapping & Formatting Instructions:

• Basic Tags:

  • \name{} -> @name
  • \alias{} -> @aliases
  • \title{} -> The first line/title of the Roxygen block (no tag needed).
  • \description{} -> @description
  • \details{} -> @details
  • \author{} -> @author
  • \references{} -> @references
  • \seealso{} -> @seealso
  • \examples{} -> @examples (Preserve all \dontrun{...} blocks exactly as they are).

• Arguments & Nested Lists: * Map \arguments{} into individual @param [name] [description] tags for each primary \item{}.

  • If an argument contains a nested list (e.g., a \describe{ \item{...}{...} } block inside the control argument), convert the nested items into an indented Markdown bulleted list under that @param's description.
    • Format: * [item_name]: [item description]

• Sections & Returns: * Translate \section{title}{...} to @section title: ...

  • Translate \value{...} to @return. Because the .Rd file uses \item{name}{description} inside \value{}, convert these items into a Markdown bulleted list under the @return tag.
    • Format: * [name]: [description]

• Internal vs. Export: * Check the .Rd file for \keyword{internal}.

  • If \keyword{internal} exists, add @keywords internal to the Roxygen block and DO NOT add an @export tag.
  • If \keyword{internal} does not exist, append @export to the bottom of the Roxygen block (just above the function definition).

• Links: Convert .Rd links to Roxygen2 Markdown links:

  • \link{function} -> [function()]
  • \link[package]{function} -> [package::function()]
  • \href{url}{text} -> [text](url)

• Math (CRITICAL): R package documentation requires specific math tags. Do not convert math into standard Markdown or LaTeX $ or $$ tags. You must meticulously preserve the exact R documentation math macros, including the two-argument fallback structure: \eqn{latex}{ascii} for inline math and \deqn{latex}{ascii} for display math.

Notes:

1. Once done you can delete the file man/CSEGriskfigure.Rd.
2. Update the DESCRIPTION file to use Roxygen.
3. If possible, test that the package builds and that the pdf of the documentation builds.
   </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Convert man/CSEGriskfigure.Rd to a Roxygen2 Markdown header in `R/CSEGriskfigure.R #1

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[eeholmes-uw]

@copilot Can you test that the package builds and run the documentation using
rocker/r-ver:latest docker image?

I want you to look at the html created for the CSEGriskfigure function and also look at the pdf. Ideally I want to look at these but I am not sure you can show those to me.

I am also concerned that this is not going to look right. Like I am concerned it will all be one line, but I don't know that.

@details
#' Panel 1: Time-series plot of the data.
#' Panel 2: CDF of extinction risk.
#' Panel 3: PDF of time to reach threshold.
#' Panel 4: Probability of reaching different thresholds during forecast period.
#' Panel 5: Sample projections.
#' Panel 6: TMU plot (uncertainty as a function of the forecast).

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• cloud.r-project.org
  • Triggering command: /usr/local/lib/R/bin/exec/R /usr/local/lib/R/bin/exec/R --no-save --no-restore --no-echo --no-restore -e ~n~~+~~+~~+~~+~install.packages(c('roxygen2','generics','KFAS','mvtnorm','nlme','remotes'),~+~repos='REDACTED',~+~quiet=TRUE)~n~~+~~+~ (dns block)
  • Triggering command: /usr/local/lib/R/bin/exec/R /usr/local/lib/R/bin/exec/R --no-save --no-restore --no-echo --no-restore -e tryCatch(readLines(url('REDACTED'),~+~n=2),~+~error=function(e)~+~paste('BLOCKED:',~+~e$message)) e (dns block)
  • Triggering command: /usr/lib/R/bin/exec/R /usr/lib/R/bin/exec/R --no-echo --no-restore -e tryCatch(readLines(url('REDACTED'),~+~n=2),~+~error=function(e)~+~paste('BLOCKED:',~+~e$message)) 4.deb y /usr/bin/mktemp ntime.v2.task/mobasename -libfontconfig-d/tmp/tmp.Sy2HtrZOGF b mktemp mon/�� 50bd2598eece83ec03c0b95573087468 rm ch stall-BwTGE4/173gzip /var/lib/dpkg/tm-d /usr/sbin/dpkg-deb kpsewhich (dns block)
• packagemanager.posit.co
  • Triggering command: /usr/local/lib/R/bin/exec/R /usr/local/lib/R/bin/exec/R --no-save --no-restore --no-echo --no-restore -e tryCatch(readLines(url('REDACTED'),~+~n=2),~+~error=function(e)~+~paste('BLOCKED:',~+~e$message)) f5405d7e0c2d3fdcc0bb6e24d73ef67903d/log.json 0b603cec2db1833cecd083068d0375ebf93/init.pid - (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[eeholmes-uw]

@copilot ok get rid of the GitHub action. I just want you to be able to test the html produced from the Rd file. Can you install R and then run something like this

Install roxygen2 if it isn't already installed

if (!requireNamespace("roxygen2", quietly = TRUE)) install.packages("roxygen2", repos = "https://cloud.r-project.org")

Generate the .Rd file strictly from the Roxygen headers (skipping full package load if possible)

roxygen2::roxygenize(roclets = "rd")

Convert the resulting .Rd file to a standalone HTML file

tools::Rd2HTML("man/CSEGriskfigure.Rd", out = "CSEGriskfigure_preview.html")

[Copilot]

@copilot ok get rid of the GitHub action. I just want you to be able to test the html produced from the Rd file. Can you install R and then run something like this

Install roxyg...

Done in commit 7cab275. Here's what was done:

1. Removed .github/workflows/check-and-docs.yaml as requested.
2. Installed R locally, then ran exactly the snippet you asked for:

   roxygen2::roxygenize(roclets = "rd")
   tools::Rd2HTML("man/CSEGriskfigure.Rd", out = "CSEGriskfigure_preview.html")

3. Committed CSEGriskfigure_preview.html to the PR branch so you can download/view it directly from GitHub.

The @details section is not one line — the Markdown * Panel N: bullet list in the Roxygen source generates a proper <ul> list in the HTML, with each panel on its own <li>:

<h3>Details</h3>
<ul>
  <li>Panel 1: Time-series plot of the data.</li>
  <li>Panel 2: CDF of extinction risk.</li>
  <li>Panel 3: PDF of time to reach threshold.</li>
  <li>Panel 4: Probability of reaching different thresholds during forecast period.</li>
  <li>Panel 5: Sample projections.</li>
  <li>Panel 6: TMU plot (uncertainty as a function of the forecast).</li>
</ul>

You can view the full HTML at:
https://raw.githubusercontent.com/eeholmes-uw/MARSS/copilot/convert-manual-to-roxygen2/CSEGriskfigure_preview.html

[eeholmes-uw]

@copilot

Can you add a pdf?

if (!requireNamespace("tinytex", quietly = TRUE)) install.packages("tinytex", repos = "https://cloud.r-project.org")
tinytex::install_tinytex()

Generate the Rd file:
roxygen2::roxygenize(roclets = "rd")

Build the PDF: Run this in the terminal:
R CMD Rd2pdf man/CSEGriskfigure.Rd --output=CSEGriskfigure_preview.pdf

or similar

[Copilot]

@copilot

Can you add a pdf?
...

Done in commit d9c1cb9. Ran R CMD Rd2pdf after roxygen2::roxygenize() and committed the resulting CSEGriskfigure_preview.pdf (3 pages) to the branch.

You can download it from:
https://github.com/eeholmes-uw/MARSS/raw/copilot/convert-manual-to-roxygen2/CSEGriskfigure_preview.pdf

The only warnings during PDF generation were pdfTeX warning (dest) for cross-references to other MARSS functions (e.g., MARSSboot, marssMLE) that don't exist in the minimal one-file scratch package — these will resolve fine when the full package is built. No errors.

[eeholmes-uw]

@copilot

Now repeat for the rest of the files in the R directory. If conversion is ambiguous and you really cannot figure out what to do, skip that file and report the ambiguity. But do the rest of the files.

At the end, create a PDF of the documentation using
R CMD Rd2pdf . --output=MARSS_Manual.pdf
or similar.

You can remove the CSEGriskfigure_preview files.

Remember that markdown=TRUE and ensure that lines will not run into each other, for example
a
b
c
would become abc