Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Developer Issue]: Documenting things using Rcpp or C++ #635

Open
kellijohnson-NOAA opened this issue Jun 19, 2024 · 0 comments
Open

[Developer Issue]: Documenting things using Rcpp or C++ #635

kellijohnson-NOAA opened this issue Jun 19, 2024 · 0 comments
Assignees
Labels
kind: documentation Improvements or additions to documentation kind: question Further information is requested P2 mid-level priority status: needs discussion Dialogue is needed before a decision can be made. theme: documentation
Milestone

Comments

@kellijohnson-NOAA
Copy link
Contributor

We should document units alongside code but which method of doing that is unclear. Below are options and some questions

  1. Should we document units alongside the C++ code and display them on the Doxygen website (e.g., updating the documentation near log_rzero to include the units
    https://github.com/NOAA-FIMS/FIMS/blob/main/inst/include/population_dynamics/recruitment/functors/recruitment_base.hpp#L42

  2. Should we document units in the Rcpp interface following approach 4 listed here? For example, we can document units in the age comp data interface:

Rcpp::class_<AgeCompDataInterface>("AgeComp")
      .constructor<int, int>()
      .field("age_comp_data",
              &AgeCompDataInterface::age_comp_data,
              "Age composition data can be in either numbers or proportions")
      .method("get_id",
              &AgeCompDataInterface::get_id,
              "Get the ID of the age composition interface");

Then user can view the documentation in R

> FIMS::AgeComp
C++ class 'AgeComp' <000001cdcbc66d20>
Constructors:
    AgeComp(int, int)

Fields: 
    Rcpp::Vector<14, Rcpp::PreserveStorage> age_comp_data
        docstring : Age composition data can be in either numbers or proportions

Methods: 
     unsigned int get_id()  
           docstring : Get the ID of the age composition interface
  1. Can we use TMB for documenting them? For example, by modifying reporting section in model.hpp?

Originally posted by @Bai-Li-NOAA in #561 (comment)

@kellijohnson-NOAA kellijohnson-NOAA added kind: documentation Improvements or additions to documentation kind: question Further information is requested status: triage_needed This is not approved for this milestone, do not work on it yet status: needs discussion Dialogue is needed before a decision can be made. P2 mid-level priority theme: documentation labels Jun 19, 2024
@kellijohnson-NOAA kellijohnson-NOAA removed the status: triage_needed This is not approved for this milestone, do not work on it yet label Jun 25, 2024
@kellijohnson-NOAA kellijohnson-NOAA added this to the Parking lot milestone Jul 9, 2024
@Bai-Li-NOAA Bai-Li-NOAA linked a pull request Jul 24, 2024 that will close this issue
kellijohnson-NOAA added a commit that referenced this issue Sep 1, 2024
Was PR #652 and commit e0fbfb0 but
that was based on main and enough has changed that the commit had be
redone for dev. There are still some interfaces that are not documented
but they can be completed in #662.

Thanks to @Bai-Li-NOAA for this commit :)

Close #635
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind: documentation Improvements or additions to documentation kind: question Further information is requested P2 mid-level priority status: needs discussion Dialogue is needed before a decision can be made. theme: documentation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants