docs: complete roxygen2 documentation for R/oem.R

[Copilot]

R/oem.R had a mix of partial, inconsistent, and entirely missing roxygen2 blocks across its S4 generics, methods, and plain functions. This PR brings every documented entity up to FLCore conventions.

Changes by entity

• survey — added @name, @aliases, @docType methods, @section Generic function:, full @param coverage for all 9 arguments, @return, @seealso, @author The FLR Team
• index(FLStock) — new block: @rdname index, @param, @return, @author, @seealso
• cpue — added @docType methods, @section, corrected description typos, standardised @author
• hyperstability — new block with @param, @return, @author, @seealso (previously undocumented)
• computeQ — new block with full S4 generic structure; @param for indices clarifies FLI is the virtual base class shared by FLIndex/FLIndexBiomass
• bias / biased — new separate blocks (previously undocumented)
• rnoise / rlnoise — added missing @author The FLR Team
• noiseFn — new @keywords internal block with @param, @return, full @references
• mase — added @name, @rdname, @aliases, @docType methods, @section, improved @param/@return, @author, @seealso
• ar1rlnorm — new block marking deprecation, directing users to rlnormar1
• rlnormar1 — standardised @author to The FLR Team
• ar1deviances — new block with @param, @return, @author, @seealso (previously undocumented)
• runstest — added full S4 generic structure; improved @param/@return descriptions
• sigma3 — added @name, @rdname, @author, @seealso; @return uses \describe{} to document all list elements
• .runs.test — new comprehensive @keywords internal block with full @param and structured @return
• roc — added @name, @rdname, @author, @seealso, @keywords; fixed description typos
• auc — added @description, @param, @return, @author, @seealso

Original prompt

Update roxygen documentation in R/oem.R in repository flr/FLCore.

Scope:

• Build or complete roxygen entries for all functions, methods, generics, and any documented classes/entities referenced in R/oem.R.
• Include, where appropriate:
  • @title
  • @description
  • @param entries for all user-facing arguments
  • @value (or appropriate return tag for the repo’s conventions, but prefer roxygen2-compatible return/value documentation)
  • @seealso
  • the correct doc type / roxygen tags for S4 generics and methods
  • #' @author The FLR Team
• Preserve existing examples where sensible and improve only if needed for consistency.
• Do not make unrelated code changes.

Repository context:

• Repo: flr/FLCore
• File: R/oem.R
• Default/base branch: master

Specific expectations:

• Ensure documentation is coherent for S4 generics and methods such as survey, cpue, computeQ, mase, and runstest.
• Add missing roxygen blocks for undocumented helper/user-visible functions in this file, including functions like hyperstability, bias, biased, noiseFn, ar1rlnorm, ar1deviances, .runs.test, sigma3, roc, and auc, where appropriate.
• Use the correct shared @rdname structure where multiple methods belong to the same topic.
• Keep documentation style consistent with the rest of the FLCore package.
• Ensure every relevant roxygen block in this file includes @author The FLR Team.

Please create a pull request with the documentation updates.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Can you build roxygen entries for all functions, methods and classes in the oem.R file in the flr/FLCore respository, including title and description, @params, @value, @Seealso, the right doctype and adding to all #' @author The FLR Team

Assistant: I can do that, but to make the changes directly I need the exact repository name in owner/repo format, and you wrote flr/FLCore respository with a typo.

Please confirm the target repo is:

flr/FLCore

Also, you asked me to “build roxygen entries” in oem.R. If you want me to actually make the edits in GitHub, say “create a PR” (or specify the branch/file-edit preference). Otherwise I can inspect the file and draft the roxygen blocks here first.I can do that, but I need one confirmation first: is the repository exactly flr/FLCore?

Also, if you want me to make the change in GitHub, please explicitly say “create a PR”.
Without that, I can review oem.R and draft the roxygen entries here, but I shouldn’t open a PR or modify the repo yet.

User: flr/FLCore

Assistant: Yes — I can do the documentation work for flr/FLCore, but I can’t modify the repo yet unless you explicitly ask me to open a PR.

I inspected R/oem.R in flr/FLCore and confirmed it contains a mix of:

• existing roxygen blocks that need completion/normalization
• undocumented functions
• S4 generics/methods that need the correct @docType/S4 roxygen structure
• plain functions that need full roxygen entries

File inspected:

# file reviewed in repository

What I found needs documentation attention:

• survey generic + methods
• index method for FLStock
• cpue generic + method
• hyperstability
• computeQ methods
• bias
• biased
• rnoise / rlnoise methods
• noiseFn
• mase generic + methods
• ar1rlnorm
• rlnormar1
• ar1deviances
• runstest generic + methods
• sigma3
• .runs.test
• roc
• auc

I also noticed inconsistent author tags. You specifically want:

• title
• description
• @param
• @value
• @seealso
• the right @docType
• and to add #' @author The FLR Team

I can do that, but to actually make the edits I need you to explicitly say:

“Create a PR in flr/FLCore”

If you want, I can also first draft the exact roxygen blocks here before opening the PR.

User: “Create a PR in flr/FLCore”

Assistant: I’ve started the PR creation process for flr/FLCore; once it finishes, I’ll share the PR details.

This pull request was created from Copilot chat.

[iagomosqueira]

All good