doc(rcpp): Uses 3rd entry to document rcpp

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

inst/include/interface/rcpp/rcpp_objects/rcpp_data.hpp

@@ -128,7 +128,7 @@ class AgeCompDataInterface : public DataInterfaceBase {
 class IndexDataInterface : public DataInterfaceBase {
  public:
   int ymax;                       /**< second dimension of the data */
-  Rcpp::NumericVector index_data; /**<the age composition data*/
+  Rcpp::NumericVector index_data; /**<the index data*/
 
   /**
    * @brief constructor

inst/include/interface/rcpp/rcpp_objects/rcpp_fleet.hpp

@@ -57,9 +57,9 @@ class FleetInterface : public FleetInterfaceBase {
   bool is_survey = false; /**< whether this is a survey fleet */
   int nages;              /**< number of ages in the fleet data*/
   int nyears;             /**< number of years in the fleet data */
-  double log_q;           /**< log of catchability for the fleet*/
+  double log_q;           /**< natural log of catchability for the fleet*/
   ParameterVector
-      log_Fmort;           /**< log of fishing mortality rate for the fleet*/
+      log_Fmort;           /**< natural log of fishing mortality rate for the fleet*/
   ParameterVector log_expected_index; /**< expected index of abundance for the survey */
   ParameterVector proportion_catch_numbers_at_age; /**< expected catch numbers at age for the fleet */
   bool estimate_q = false; /**< whether the parameter q should be estimated*/

inst/include/interface/rcpp/rcpp_objects/rcpp_population.hpp

@@ -60,8 +60,8 @@ class PopulationInterface : public PopulationInterfaceBase {
   uint32_t maturity_id;      /**< id of the maturity function*/
   uint32_t growth_id;        /**< id of the growth function*/
   uint32_t recruitment_id;   /**< id of the recruitment function*/
-  ParameterVector log_M; /**< log of the natural mortality of the stock*/
-  ParameterVector log_init_naa; /**<log of the initial numbers at age*/
+  ParameterVector log_M; /**< natural log of the natural mortality of the population*/
+  ParameterVector log_init_naa; /**<natural log of the initial numbers at age*/
   ParameterVector numbers_at_age; /**<log of the initial numbers at age*/
   Rcpp::NumericVector ages; /**<vector of ages in the population; length nages*/
 
@@ -86,9 +86,9 @@ class PopulationInterface : public PopulationInterfaceBase {
   void SetGrowth(uint32_t growth_id) { this->growth_id = growth_id; }
 
   /**
-   * @brief Set the unique id for the Maturity object
+   * @brief Set the unique id for the recruitment object
    *
-   * @param recruitment_id Unique id for the Maturity object
+   * @param recruitment_id Unique id for the recruitment object
    */
   void SetRecruitment(uint32_t recruitment_id) {
     this->recruitment_id = recruitment_id;

inst/include/interface/rcpp/rcpp_objects/rcpp_recruitment.hpp

@@ -64,11 +64,11 @@ std::map<uint32_t, RecruitmentInterfaceBase*>
  */
 class BevertonHoltRecruitmentInterface : public RecruitmentInterfaceBase {
  public:
-  Parameter logit_steep; /**< steepness or the productivity of the stock*/
+  Parameter logit_steep; /**< steepness or the productivity of the population*/
   Parameter log_rzero;   /**< recruitment at unfished biomass */
   Parameter
-      log_sigma_recruit; /**< the log of the stock recruit standard deviation */
-  ParameterVector log_devs;   /**< log recruitment deviations*/
+      log_sigma_recruit; /**< the natural log of the stock recruit standard deviation */
+  ParameterVector log_devs;   /**< natural log recruitment deviations*/
   bool estimate_log_devs = false; /**< boolean describing whether to estimate */
 
   BevertonHoltRecruitmentInterface() : RecruitmentInterfaceBase() {}

inst/include/interface/rcpp/rcpp_objects/rcpp_tmb_distribution.hpp

@@ -127,10 +127,10 @@ class DnormDistributionsInterface : public DistributionsInterfaceBase {
 
   /**
    * @brief Evaluate normal probability density function, default returns the
-   * log of the pdf
+   * natural log of the pdf
    *
    * @tparam T
-   * @return log pdf
+   * @return natural log of the pdf
    */
   virtual double evaluate() {
     fims_distributions::NormalLPDF<double> dnorm;
@@ -265,10 +265,10 @@ class DlnormDistributionsInterface : public DistributionsInterfaceBase {
 
   /**
    * @brief Evaluate lognormal probability density function, default returns the
-   * log of the pdf
+   * natural log of the pdf
    *
    * @tparam T
-   * @return log pdf
+   * @return natural log of the pdf
    */
   virtual double evaluate() {
     fims_distributions::LogNormalLPDF<double> dlnorm;
@@ -400,10 +400,10 @@ class DmultinomDistributionsInterface : public DistributionsInterfaceBase {
 
   /**
    * @brief Evaluate multinom probability density function, default returns the
-   * log of the pdf
+   * natural log of the pdf
    *
    * @tparam T
-   * @return log pdf
+   * @return natural log of the pdf
    */
   virtual double evaluate() {
     fims_distributions::MultinomialLPMF<double> dmultinom;

inst/include/population_dynamics/fleet/fleet.hpp

@@ -35,11 +35,11 @@ struct Fleet : public fims_model_object::FIMSObject<Type> {
 
   // Mortality and catchability
   fims::Vector<Type>
-      log_Fmort; /*!< estimated parameter: log Fishing mortality*/
-  Type log_q;    /*!< estimated parameter: catchability of the fleet */
+      log_Fmort; /*!< estimated parameter: natural log Fishing mortality*/
+  Type log_q;    /*!< estimated parameter: natural log of catchability of the fleet */
 
   fims::Vector<Type> Fmort; /*!< transformed parameter: Fishing mortality*/
-  Type q; /*!< transofrmed parameter: the catchability of the fleet */
+  Type q; /*!< transformed parameter: the catchability of the fleet */
 
   // derived quantities
   fims::Vector<Type> catch_at_age;    /*!<derived quantity catch at age*/
@@ -61,7 +61,7 @@ struct Fleet : public fims_model_object::FIMSObject<Type> {
   fims::Vector<Type> catch_numbers_at_age; /*!<model expected catch at age*/
   fims::Vector<Type> proportion_catch_numbers_at_age; /*!<model expected catch at age*/
   fims::Vector<Type> catch_weight_at_age;  /*!<model expected weight at age*/
-  bool is_survey = false;                  /*!< is this fleet object a survey*/
+  bool is_survey = false;                  /*!< is this fleet object a survey, compared to being a fishing fleet*/
 
 #ifdef TMB_MODEL
   ::objective_function<Type> *of;
@@ -99,8 +99,8 @@ struct Fleet : public fims_model_object::FIMSObject<Type> {
   }
 
   /**
-   * @brief Prepare to run the fleet module. Called at each model itartion, and
-   * used to exponentiate the log q and Fmort parameters prior to evaluation.
+   * @brief Prepare to run the fleet module. Called at each model iteration, and
+   * used to exponentiate the natural log q and Fmort parameters prior to evaluation.
    *
    */
   void Prepare() {
@@ -152,7 +152,7 @@ struct Fleet : public fims_model_object::FIMSObject<Type> {
   }
 
   /**
-   * Evaluate the log of the expected index.
+   * Evaluate the natural log of the expected index.
    */
   void evaluate_index() {
     for(size_t i=0; i<this->expected_index.size(); i++){

inst/include/population_dynamics/population/population.hpp

@@ -46,8 +46,8 @@ struct Population : public fims_model_object::FIMSObject<Type> {
   // parameters are estimated; after initialize in create_model, push_back to
   // parameter list - in information.hpp (same for initial F in fleet)
   fims::Vector<Type>
-      log_init_naa;         /*!< estimated parameter: log numbers at age*/
-  fims::Vector<Type> log_M; /*!< estimated parameter: log Natural Mortality*/
+      log_init_naa;         /*!< estimated parameter: natural log of numbers at age*/
+  fims::Vector<Type> log_M; /*!< estimated parameter: natural log of natural mortality*/
 
   // Transformed values
   fims::Vector<Type> M; /*!< transformed parameter: Natural Mortality*/
@@ -386,7 +386,7 @@ struct Population : public fims_model_object::FIMSObject<Type> {
     POPULATION_LOG << "phi0 = " << phi0 << std::endl;
     POPULATION_LOG << "spawning_biomass[year - 1] = "
                    << this->spawning_biomass[year - 1] << std::endl;
-    POPULATION_LOG << "log recruit devs = "
+    POPULATION_LOG << "natural log of recruit devs = "
                    << this->recruitment->log_recruit_devs[i_dev - 1]
                    << std::endl;
     POPULATION_LOG << "rec eval = "

inst/include/population_dynamics/recruitment/functors/recruitment_base.hpp

@@ -33,13 +33,13 @@ struct RecruitmentBase : public fims_model_object::FIMSObject<Type> {
   static uint32_t id_g; /**< reference id for recruitment object*/
 
   fims::Vector<Type>
-      log_recruit_devs; /*!< A vector of log recruitment deviations */
+      log_recruit_devs; /*!< A vector of natural log of recruitment deviations */
   bool constrain_deviations = false; /*!< A flag to indicate if recruitment
-                                 deviations are summing to zero or not */
+                                 deviations are summing to zero or not. */
 
-  fims::Vector<Type> log_sigma_recruit; /**< Log standard deviation of log recruitment
-                       deviations */
-  fims::Vector<Type> log_rzero;         /**< Log of unexploited recruitment.*/
+  fims::Vector<Type> log_sigma_recruit; /**< Natural log of the standard deviation of the natural log of recruitment
+                       deviations. */
+  fims::Vector<Type> log_rzero;         /**< Natural log of unexploited recruitment.*/
 
   bool estimate_log_recruit_devs = true; /*!< A flag to indicate if recruitment
                                   deviations are estimated or not */

inst/include/population_dynamics/recruitment/functors/sr_beverton_holt.hpp

@@ -18,19 +18,20 @@
 
 namespace fims_popdy {
 
-/** @brief BevertonHolt class that returns the Beverton Holt SR
- * from fims_math.
+/** @brief BevertonHolt class that returns the Beverton Holt stock--recruitment
+ * function from fims_math.
  *
  * @param logit_steep Recruitment relative to unfished recruitment at
- * 20% of unfished spawning biomass. Should be a value between 0.2 and 1.0.
+ * 20 percent of unfished spawning biomass. Steepness is subject to a logit
+ * transformation.
  */
 template <typename Type>
 struct SRBevertonHolt : public RecruitmentBase<Type> {
   // Here we define the members that will be used in the Beverton Holt SR
   // function. These members are needed by Beverton Holt but will not be common
   // to all recruitment functions like spawners is below.
   fims::Vector<Type> logit_steep; /**< Transformed value of recruitment relative to unfished
-                 recruitment at 20% of unfished spawning biomass.*/
+                 recruitment at 20 percent of unfished spawning biomass.*/
 
   SRBevertonHolt() : RecruitmentBase<Type>() {}
 

vignettes/fims-demo.Rmd

@@ -257,7 +257,7 @@ methods::show(BevertonHoltRecruitment)
 There are three parameters we need to set-up: *log_sigma_recruit*, *log_rzero*, and *logit_steep*.
 
 ```{r set-up-recruitment}
-recruitment$log_rzero$value <- log(1e+06) # unit: log(number)
+recruitment$log_rzero$value <- log(1e+06) # unit: ln(number)
 recruitment$log_rzero$is_random_effect <- FALSE
 recruitment$log_rzero$estimated <- TRUE
 recruitment$logit_steep$value <- -log(1.0 - 0.75) + log(0.75 - 0.2)