R & C++ documentation helper function

[e-perl-NOAA]

What is the feature?

• Add a documentation helper function in R that pops up in the IDE like ?mean or help(mean) for the roxygen and doxygen documentation as discussed in the FIMS RE implementation meeting.

How have you implemented the solution?

• Get doxygen workflow to add a file called FIMS.tag with all the function names
• fims_help() has an input query of a function and looks through the roxygen and doxygen documentation and pulls up the html file in the Rstudio/positron viewer or in a separate web browser.

NOTE: I had to develop this in my fork because I needed to change main, and actually get the pkgdown action to work so that FIMS.tag actually rendered. Thus, to test this and see how it works, you need to change the following in the fims_help() function:

doxygen_base_url <- "https://noaa-fims.github.io/FIMS/doxygen/"

to

doxygen_base_url <- "https://e-perl-noaa.github.io/FIMS/doxygen/"

and fims_help() should work.

Given that I just needed to get one small thing off my 🍽️ and just went for it 🚀 (sorry @nathanvaughan-NOAA 🤠), and because of that I'm sure there will be lots of comments, suggestions, etc. before it can get merged in.

---

Instructions for code reviewer

👋Hello reviewer👋, thank you for taking the time to review this PR!

• Please use this checklist during your review, checking off items that you have verified are complete but feel free to skip over items that are not relevant!
• See the GitHub documentation for how to comment on a PR to indicate where you have questions or changes are needed before approving the PR.
• Please use standard conventional messages for both commit messages and comments
• PR reviews are a great way to learn so feel free to share your tips and tricks. However, when suggesting changes to the PR that are optional please include nit: (for nitpicking) as the comment type. For example, nit: I prefer using a data.frame() instead of a matrix because ...
• Engage with the developer. Make it clear when the PR is approved by selecting the approved status, and potentially commenting on the PR with something like This PR is now ready to be merged.

Checklist

• The code is well-designed
• The code is designed well for both users and developers
• Code coverage remains high- [ ] Comments are clear, useful, and explain why instead of what
• Code is appropriately documented (doxygen and roxygen)

[github-actions]

🎨 Chore: code formatting workflow

Our automated workflows cannot run on forks because of permission issues, and thus, we ask that you run the following code locally and push any changes that are created to your feature branch. You will only be reminded of this once per PR. Thank you!

Format C++ code

1. Install clang-format version 18.0.0
2. Run the following command from the repository root:

   clang-format -i --style="{BasedOnStyle: Google, SortIncludes: false}" $(find ./inst/include ./src ./tests/gtest -name "*.hpp" -o -name "*.cpp")

Format R code

1. Install {styler} and {roxygen2}
2. Run the following commands in R from the repository root:

styler::style_pkg() # Style R code
roxygen2::roxygenise() # Update documentation
styler::style_pkg() # Style R code again
roxygen2::roxygenise() # Update documentation again
usethis::use_tidy_description() # Style DESCRIPTION file

Push changes

1. Commit the formatting with a commit message of "Chore: format feature branch"
2. Push to your fork

[codecov]

Codecov Report

❌ Patch coverage is 0% with 47 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.46%. Comparing base (2a5e3ad) to head (b40b36f).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
R/fims_help.R	0.00%	47 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1563      +/-   ##
==========================================
- Coverage   87.24%   84.46%   -2.78%     
==========================================
  Files          99       70      -29     
  Lines        9002     7656    -1346     
  Branches      521        0     -521     
==========================================
- Hits         7854     6467    -1387     
- Misses       1110     1189      +79     
+ Partials       38        0      -38     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[kellijohnson-NOAA]

@e-perl-NOAA I started looking at this PR by installing this version of FIMS and running one example help call and got

fims_help("bevertonholt")

Fetching FIMS C++ documentation index...
Error in value[[3L]](cond) : 
  Could not download FIMS.tag. Check internet connection.
In addition: Warning message:
In utils::download.file(tagfile_url, destfile = local_tagfile, quiet = TRUE) :
  cannot open URL 'https://noaa-fims.github.io/FIMS/doxygen/FIMS.tag': HTTP status was '404 Not Found'

even though I am positive that I have an internet connection.
Then I went down a 🐰 🕳️ on GitHub of searching for doxygen language:R and found NOTHING helpful. Next, I started looking at fims_help() even though I couldn't use the function natively. I went through step by step to see how things worked and noticed that by default for "bevertonholt" it will send you to the Rcpp documentation for BevertonHoltRecruitmentInterface because it comes first in the search. Then I did a global search for this namespace and noticed that it is listed in R/Rcpp_exports.R which leads to it being in man/Cpp_classes.Rd and you can actually use ?BevertonHoltRecruitment to get to a .Rd file that lists the same website for users to click on and navigate to the doxygen all without using the .tag file. Should we investigate using the .tag file to populate the websites that get listed in R/Rcpp_exports? Or find a way to update the file using the format GitHub workflow? Anyway, I think that we can find ways to do this without an extra function.
What do you think @e-perl-NOAA ?

[e-perl-NOAA]

@kellijohnson-NOAA did you replace line 29 with `doxygen_base_url <- "https://e-perl-noaa.github.io/FIMS/doxygen/" to run it? Also, it should tell you about the other words that have that in them for you to search in case the first thing it pulls up is not what you want.

Also, is R/Rcpp_exports.R generated automatically somewhere, or is it generated manually?

[e-perl-NOAA]

@kellijohnson-NOAA
Also, the class portion of Rcpp_exports.R could be automated from FIMS.tag but the function portion could not right now because the tag file contains low-level names like set_fixed_parameters, get_fixed_parameters_vector, logit_rcpp, inv_logit_rcpp, get_log_info, write_log, and set_log_path, while the exported R names in NAMESPACE and R/Rcpp_exports.R:48 are curated names like set_fixed, get_fixed, logit, and inv_logit, omitting some registered functions such as get_log_info, write_log, set_log_path, and init_logging. If these should actually match, then that makes it easier, but if not, there would have to be some sort of custom naming convention set up that takes into account current and future function names.

[kellijohnson-NOAA]

I made some headway automating the Rcpp_exports.R file using generate_doxygen_stubs(), a new function

`generate_doxygen_stubs()`

#' Generate Doxygen Documentation Links for R Help
#'
#' This is an internal utility function used by `roxygen2` via the `@@eval` tag
#' to dynamically construct a centralized help page mapping FIMS C++ entities 
#' to their corresponding online Doxygen documentation.
#'
#' @param tag_file_path Character. Path to the Doxygen-generated XML tag file.
#' @param base_url Character. Base URL of the FIMS pkgdown documentation site.
#'
#' @return A character vector containing formatted roxygen documentation blocks.
#' @noRd
generate_doxygen_stubs <- function(
  tag_file_path = "doxygen/html/FIMS.tag", 
  base_url = "https://e-perl-noaa.github.io/FIMS/"
) {
  
  # Fail gracefully if the Doxygen tag file doesn't exist yet
  if (!file.exists(tag_file_path)) {
    return(c(
      "@title FIMS C++ Core Doxygen Index",
      "@name fims_cpp",
      "@description Core C++ implementation links.",
      "@note Doxygen tag file not found at compilation time. Please generate the Doxygen tag file first."
    ))
  }
  
  # Ensure xml2 is available
  if (!requireNamespace("xml2", quietly = TRUE)) {
    stop("The 'xml2' package is required to parse Doxygen tag files.")
  }
  
  # Read and parse the XML tag file
  doc <- xml2::read_xml(tag_file_path)
  compounds <- xml2::xml_find_all(doc, "//compound")
  
  # Initialize documentation components
  header_lines <- c(
    "@title FIMS C++ Core Doxygen Index",
    "@name fims_cpp",
    "@description Direct entry points to the compiled core TMB/C++ documentation structure.",
    "@details",
    "Click any link below to open the official FIMS Doxygen page for that component:",
    ""
  )
  
  link_lines <- c()
  alias_lines <- c()
  
  # Iterate over all components discovered by Doxygen
  for (comp in compounds) {
    kind <- xml2::xml_attr(comp, "kind")
    
    # Filter to look specifically for classes, namespaces, and structs
    if (kind %in% c("class", "namespace", "struct")) {
      name <- xml2::xml_text(xml2::xml_find_all(comp, "./name"))
      filename <- xml2::xml_text(xml2::xml_find_all(comp, "./filename"))
      
      # Skip internal or anonymous Doxygen structures if any exist
      if (name == "" || is.na(filename)) next
      
      # Construct the direct URL to the pkgdown reference folder
      url <- paste0(base_url, "reference/html/", filename)
      
      # 1. Add a Markdown bullet point link for the help body
      link_lines <- c(link_lines, paste0("* **", name, "** (", kind, "): \\url{", url, "}"))
      
      # 2. Add an R help alias so ?name or ?class_name hooks into this page
      # Replace C++ scope resolution operators '::' with '_' to stay R-friendly
      clean_alias <- gsub("::", "_", name)
      alias_lines <- c(alias_lines, paste0("@aliases ", clean_alias))
    }
  }
  
  # Fallback if no compounds were parsed
  if (length(link_lines) == 0) {
    link_lines <- c("No C++ classes or namespaces found in the tag file.")
  }
  
  # Combine everything into a single character array for @eval to ingest
  roxygen_output <- c(
    header_lines,
    link_lines,
    "",
    "@keywords internal",
    alias_lines
  )

  return(roxygen_output)
}

where the function is used with roxygen via changing Rcpp_exports.R to be

#' @eval source("R/utils_doxygen.R"); generate_doxygen_stubs()
NULL

Then, when you run devtools::document() it creates man\fims_cpp.Rd.

man\fims_cpp.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Rcpp_exports.R
\name{fims_cpp}
\alias{fims_cpp}
\alias{AgeCompDataInterface}
\alias{BevertonHoltRecruitmentInterface}
\alias{fims_popdy_CatchAtAge}
\alias{CatchAtAgeInterface}
\alias{DataInterfaceBase}
\alias{fims_data_object_DataObject}
\alias{fims_distributions_DensityComponentBase}
\alias{fims_popdy_DimensionInfo}
\alias{DistributionsInterfaceBase}
\alias{DlnormDistributionsInterface}
\alias{DmultinomDistributionsInterface}
\alias{DnormDistributionsInterface}
\alias{fims_popdy_DoubleLogisticSelectivity}
\alias{DoubleLogisticSelectivityInterface}
\alias{fims_popdy_EWAAGrowth}
\alias{EWAAGrowthInterface}
\alias{fims_FIMSLog}
\alias{fims_model_object_FIMSObject}
\alias{FIMSRcppInterfaceBase}
\alias{fims_popdy_FisheryModelBase}
\alias{FisheryModelInterfaceBase}
\alias{fims_popdy_Fleet}
\alias{FleetInterface}
\alias{FleetInterfaceBase}
\alias{fims_popdy_GrowthBase}
\alias{GrowthInterfaceBase}
\alias{IndexDataInterface}
\alias{fims_info_Information}
\alias{fims_JsonParser}
\alias{fims_JsonValue}
\alias{LandingsDataInterface}
\alias{LengthCompDataInterface}
\alias{fims_popdy_LogDevs}
\alias{LogDevsRecruitmentInterface}
\alias{fims_LogEntry}
\alias{fims_popdy_LogisticMaturity}
\alias{LogisticMaturityInterface}
\alias{fims_popdy_LogisticSelectivity}
\alias{LogisticSelectivityInterface}
\alias{fims_distributions_LogNormalLPDF}
\alias{fims_popdy_LogR}
\alias{LogRRecruitmentInterface}
\alias{fims_popdy_MaturityBase}
\alias{MaturityInterfaceBase}
\alias{fims_model_Model}
\alias{fims_distributions_MultinomialLPMF}
\alias{fims_distributions_NormalLPDF}
\alias{Parameter}
\alias{ParameterVector}
\alias{fims_popdy_Population}
\alias{PopulationInterface}
\alias{PopulationInterfaceBase}
\alias{RealVector}
\alias{fims_popdy_RecruitmentBase}
\alias{RecruitmentInterfaceBase}
\alias{fims_popdy_SelectivityBase}
\alias{SelectivityInterfaceBase}
\alias{SharedBoolean}
\alias{SharedInt}
\alias{SharedReal}
\alias{SharedString}
\alias{fims_popdy_SRBevertonHolt}
\alias{fims_popdy_Subpopulation}
\alias{fims_Vector}
\alias{fims_popdy}
\title{FIMS C++ Core Doxygen Index}
\description{
Direct entry points to the compiled core TMB/C++ documentation structure.
}
\details{
Click any link below to open the official FIMS Doxygen page for that component:
\itemize{
\item \strong{AgeCompDataInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_age_comp_data_interface.html}
\item \strong{BevertonHoltRecruitmentInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_beverton_holt_recruitment_interface.html}
\item \strong{fims_popdy::CatchAtAge} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/classfims__popdy_1_1_catch_at_age.html}
\item \strong{CatchAtAgeInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_catch_at_age_interface.html}
\item \strong{DataInterfaceBase} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_data_interface_base.html}
\item \strong{fims_data_object::DataObject} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__data__object_1_1_data_object.html}
\item \strong{fims_distributions::DensityComponentBase} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__distributions_1_1_density_component_base.html}
\item \strong{fims_popdy::DimensionInfo} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__popdy_1_1_dimension_info.html}
\item \strong{DistributionsInterfaceBase} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_distributions_interface_base.html}
\item \strong{DlnormDistributionsInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_dlnorm_distributions_interface.html}
\item \strong{DmultinomDistributionsInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_dmultinom_distributions_interface.html}
\item \strong{DnormDistributionsInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_dnorm_distributions_interface.html}
\item \strong{fims_popdy::DoubleLogisticSelectivity} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__popdy_1_1_double_logistic_selectivity.html}
\item \strong{DoubleLogisticSelectivityInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_double_logistic_selectivity_interface.html}
\item \strong{fims_popdy::EWAAGrowth} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__popdy_1_1_e_w_a_a_growth.html}
\item \strong{EWAAGrowthInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_e_w_a_a_growth_interface.html}
\item \strong{fims::FIMSLog} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/classfims_1_1_f_i_m_s_log.html}
\item \strong{fims_model_object::FIMSObject} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__model__object_1_1_f_i_m_s_object.html}
\item \strong{FIMSRcppInterfaceBase} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_f_i_m_s_rcpp_interface_base.html}
\item \strong{fims_popdy::FisheryModelBase} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/classfims__popdy_1_1_fishery_model_base.html}
\item \strong{FisheryModelInterfaceBase} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_fishery_model_interface_base.html}
\item \strong{fims_popdy::Fleet} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__popdy_1_1_fleet.html}
\item \strong{FleetInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_fleet_interface.html}
\item \strong{FleetInterfaceBase} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_fleet_interface_base.html}
\item \strong{fims_popdy::GrowthBase} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__popdy_1_1_growth_base.html}
\item \strong{GrowthInterfaceBase} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_growth_interface_base.html}
\item \strong{IndexDataInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_index_data_interface.html}
\item \strong{fims_info::Information} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/classfims__info_1_1_information.html}
\item \strong{fims::JsonParser} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/classfims_1_1_json_parser.html}
\item \strong{fims::JsonValue} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/classfims_1_1_json_value.html}
\item \strong{LandingsDataInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_landings_data_interface.html}
\item \strong{LengthCompDataInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_length_comp_data_interface.html}
\item \strong{fims_popdy::LogDevs} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__popdy_1_1_log_devs.html}
\item \strong{LogDevsRecruitmentInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_log_devs_recruitment_interface.html}
\item \strong{fims::LogEntry} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims_1_1_log_entry.html}
\item \strong{fims_popdy::LogisticMaturity} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__popdy_1_1_logistic_maturity.html}
\item \strong{LogisticMaturityInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_logistic_maturity_interface.html}
\item \strong{fims_popdy::LogisticSelectivity} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__popdy_1_1_logistic_selectivity.html}
\item \strong{LogisticSelectivityInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_logistic_selectivity_interface.html}
\item \strong{fims_distributions::LogNormalLPDF} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__distributions_1_1_log_normal_l_p_d_f.html}
\item \strong{fims_popdy::LogR} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__popdy_1_1_log_r.html}
\item \strong{LogRRecruitmentInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_log_r_recruitment_interface.html}
\item \strong{fims_popdy::MaturityBase} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__popdy_1_1_maturity_base.html}
\item \strong{MaturityInterfaceBase} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_maturity_interface_base.html}
\item \strong{fims_model::Model} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/classfims__model_1_1_model.html}
\item \strong{fims_distributions::MultinomialLPMF} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__distributions_1_1_multinomial_l_p_m_f.html}
\item \strong{fims_distributions::NormalLPDF} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__distributions_1_1_normal_l_p_d_f.html}
\item \strong{Parameter} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_parameter.html}
\item \strong{ParameterVector} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_parameter_vector.html}
\item \strong{fims_popdy::Population} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__popdy_1_1_population.html}
\item \strong{PopulationInterface} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_population_interface.html}
\item \strong{PopulationInterfaceBase} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_population_interface_base.html}
\item \strong{RealVector} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_real_vector.html}
\item \strong{fims_popdy::RecruitmentBase} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__popdy_1_1_recruitment_base.html}
\item \strong{RecruitmentInterfaceBase} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_recruitment_interface_base.html}
\item \strong{fims_popdy::SelectivityBase} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__popdy_1_1_selectivity_base.html}
\item \strong{SelectivityInterfaceBase} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_selectivity_interface_base.html}
\item \strong{SharedBoolean} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_shared_boolean.html}
\item \strong{SharedInt} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_shared_int.html}
\item \strong{SharedReal} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_shared_real.html}
\item \strong{SharedString} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/class_shared_string.html}
\item \strong{fims_popdy::SRBevertonHolt} (struct): \url{https://e-perl-noaa.github.io/FIMS/reference/html/structfims__popdy_1_1_s_r_beverton_holt.html}
\item \strong{fims_popdy::Subpopulation} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/classfims__popdy_1_1_subpopulation.html}
\item \strong{fims::Vector} (class): \url{https://e-perl-noaa.github.io/FIMS/reference/html/classfims_1_1_vector.html}
\item \strong{fims_popdy} (namespace): \url{https://e-perl-noaa.github.io/FIMS/reference/html/namespacefims__popdy.html}
}
}
\keyword{internal}

and ?RealVector takes you to a page that looks like this screenshot

So, it is not as great as @e-perl-NOAA's internal viewing of the doxygen but I think that it is an improvement on not editing R/Rcpp_exports.R by hand. Where should we go from here? Is the use of ?ReaLVector going to a list of links good enough or do we want to keep fims_help()?