chore: Remove authors, email from file headers, some cleanup to cpp f…

…ile header (#695)

* chore: Removes authors, email from file headers

Cleans up file headers to be consistent with use of @file, @brief, @details, and @copyright for every file in inst/include and notes TODO: for things that need actual documentation instead of just a place holder. There are lots of TODOs :)

Co-authored-by: Jane Sullivan <[email protected]>
Co-authored-by: Ian Taylor <[email protected]>
Co-authored-by: Kathryn Doering <[email protected]>
Co-authored-by: kellijohnson-NOAA <[email protected]>

inst/include/common/data_object.hpp

@@ -1,34 +1,10 @@
-/*
- * File:   data_object.hpp
- *
- * Author: Matthew Supernaw
- * National Oceanic and Atmospheric Administration
- * National Marine Fisheries Service
- * Email: [email protected], [email protected]
- *
- * Created on March 24, 2022, 2:37 PM
- *
- * This File is part of the NOAA, National Marine Fisheries Service
- * Fisheries Integrated Modeling System project.
- *
- * This software is a "United States Government Work" under the terms of the
- * United States Copyright Act.  It was written as part of the author's official
- * duties as a United States Government employee and thus cannot be copyrighted.
- * This software is freely available to the public for use. The National Oceanic
- * And Atmospheric Administration and the U.S. Government have not placed any
- * restriction on its use or reproduction.  Although all reasonable efforts have
- * been taken to ensure the accuracy and reliability of the software and data,
- * the National Oceanic And Atmospheric Administration and the U.S. Government
- * do not and cannot warrant the performance or results that may be obtained by
- * using this  software or data. The National Oceanic And Atmospheric
- * Administration and the U.S. Government disclaim all warranties, express or
- * implied, including warranties of performance, merchantability or fitness
- * for any particular purpose.
- *
- * Please cite the author(s) in any work or product based on this material.
- *
+/**
+ * @file data_object.hpp
+ * @brief TODO: provide a brief description.
+ * @copyright This file is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the source
+ * folder for reuse information.
  */
-
 #ifndef FIMS_COMMON_DATA_OBJECT_HPP
 #define FIMS_COMMON_DATA_OBJECT_HPP
 

inst/include/common/def.hpp

@@ -1,12 +1,9 @@
-/** \file def.hpp
- */
-
-/*
- * File:   def.hpp
- *
- * This File is part of the NOAA, National Marine Fisheries Service
- * Fisheries Integrated Modeling System project. See LICENSE in the
- * source folder for reuse information.
+/**
+ * @file def.hpp
+ * @brief TODO: provide a brief description.
+ * @copyright This file is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the source
+ * folder for reuse information.
  */
 #ifndef DEF_HPP
 #define DEF_HPP

inst/include/common/fims_math.hpp

@@ -1,15 +1,9 @@
-/** \file fims_math.hpp
- */
-// note: To document a global C function, typedef, enum or preprocessor
-// definition you must first document the file that contains it
-
-/*
- * File:   fims_math.hpp
- *
- * This File is part of the NOAA, National Marine Fisheries Service
- * Fisheries Integrated Modeling System project. See LICENSE in the
- * source folder for reuse information.
- *
+/**
+ * @file fims_math.hpp
+ * @brief TODO: provide a brief description.
+ * @copyright This file is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the source
+ * folder for reuse information.
  */
 #ifndef FIMS_MATH_HPP
 #define FIMS_MATH_HPP

inst/include/common/fims_vector.hpp

@@ -1,3 +1,10 @@
+/**
+ * @file fims_vector.hpp
+ * @brief TODO: provide a brief description.
+ * @copyright This file is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the source
+ * folder for reuse information.
+ */
 #ifndef FIMS_VECTOR_HPP
 #define FIMS_VECTOR_HPP
 
@@ -492,6 +499,14 @@ bool operator==(const fims::Vector<T>& lhs, const fims::Vector<T>& rhs)
 
 } // namespace fims
 
+/**
+ * @brief TODO: provide a brief description.
+ * 
+ * @tparam Type 
+ * @param out TODO: provide a brief description.
+ * @param v A vector.
+ * @return std::ostream& 
+ */
 template<typename Type>
 std::ostream& operator<<(std::ostream& out, fims::Vector<Type>& v)
 {

inst/include/common/information.hpp

@@ -1,9 +1,9 @@
-/** \file information.hpp
- *
- * This File is part of the NOAA, National Marine Fisheries Service
- * Fisheries Integrated Modeling System project. See LICENSE in the
- * source folder for reuse information.
- *
+/**
+ * @file information.hpp
+ * @brief TODO: provide a brief description.
+ * @copyright This file is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the source
+ * folder for reuse information.
  */
 
 #ifndef FIMS_COMMON_INFORMATION_HPP

inst/include/common/model.hpp

@@ -1,17 +1,9 @@
-/*
- * File:   model.hpp
- *
- * Author: Matthew Supernaw, Andrea Havron
- * National Oceanic and Atmospheric Administration
- * National Marine Fisheries Service
- * Email: [email protected], [email protected]
- *
- * Created on September 30, 2021, 1:08 PM
- *
- * This File is part of the NOAA, National Marine Fisheries Service
- * Fisheries Integrated Modeling System project. See LICENSE in the
- * source folder for reuse information.
- *
+/**
+ * @file model.hpp
+ * @brief TODO: provide a brief description.
+ * @copyright This file is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the source
+ * folder for reuse information.
  */
 #ifndef FIMS_COMMON_MODEL_HPP
 #define FIMS_COMMON_MODEL_HPP

inst/include/common/model_object.hpp

@@ -1,10 +1,9 @@
-/*
- * File:   model_object.hpp
- *
- * This File is part of the NOAA, National Marine Fisheries Service
- * Fisheries Integrated Modeling System project. See LICENSE in the
- * source folder for reuse information.
- *
+/**
+ * @file model_object.hpp
+ * @brief TODO: provide a brief description.
+ * @copyright This file is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the source
+ * folder for reuse information.
  */
 
 #ifndef FIMS_COMMON_MODEL_OBJECT_HPP

inst/include/distributions/distributions.hpp

@@ -1,15 +1,12 @@
-/*
- *
- * This File is part of the NOAA, National Marine Fisheries Service
- * Fisheries Integrated Modeling System project. See LICENSE in the
- * source folder for reuse information.
- *
- * Distributions module file
- * The purpose of this file is to include any .hpp files within the
+/**
+ * @file distributions.hpp
+ * @brief This distributions module includes any .hpp files within the
  * subfolders so that only this file needs to included in the model.hpp file.
- *
- * DEFINE guards for distributions module outline to define the
+ * @details Defines guards for distributions module outline to define the
  * distributions hpp file if not already defined.
+ * @copyright This file is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the source
+ * folder for reuse information.
  */
 #ifndef FIMS_DISTRIBUTIONS_HPP
 #define FIMS_DISTRIBUTIONS_HPP

inst/include/distributions/functors/density_components_base.hpp

@@ -1,16 +1,13 @@
 
-/** \file density_components_base.hpp
- * This File is part of the NOAA, National Marine Fisheries Service
- * Fisheries Integrated Modeling System project. See LICENSE in the
- * source folder for reuse information.
- *
- *
- * density_components_base file
- * The purpose of this file is to declare the DensityComponentBase class
- * which is the base class for all distribution functors.
-
- * DEFINE guards for distributions module outline to define the
+/**
+ * @file density_components_base.hpp
+ * @brief Declares the DensityComponentBase class, which is the base class for
+ * all distribution functors.
+ * @details Defines guards for distributions module outline to define the
  * density_components_base hpp file if not already defined.
+ * @copyright This file is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the source
+ * folder for reuse information.
  */
 #ifndef DENSITY_COMPONENT_BASE_HPP
 #define DENSITY_COMPONENT_BASE_HPP

inst/include/distributions/functors/lognormal_lpdf.hpp

@@ -1,14 +1,11 @@
-/*
- * File:   lognormal_lpdf.hpp
- *
- * This File is part of the NOAA, National Marine Fisheries Service
- * Fisheries Integrated Modeling System project. See LICENSE in the
- * source folder for reuse information.
- *
- * Lognormal Log Probability Density Function (LPDF) module file
- * The purpose of this file is to define the Lognormal LPDF class and its fields
- * and return the log probability density function.
- *
+/**
+ * @file lognormal_lpdf.hpp
+ * @brief Lognormal Log Probability Density Function (LPDF) defines the
+ * Lognormal LPDF class and its fields and returns the log probability density
+ * function.
+ * @copyright This file is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the source
+ * folder for reuse information.
  */
 #ifndef LOGNORMAL_LPDF
 #define LOGNORMAL_LPDF

inst/include/distributions/functors/multinomial_lpmf.hpp

@@ -1,16 +1,12 @@
-/*
- * File:   multinomial_lpmf.hpp
- *
- * This File is part of the NOAA, National Marine Fisheries Service
- * Fisheries Integrated Modeling System project. See LICENSE in the
- * source folder for reuse information.
- *
- * Multinomial Log Probability Mass Function (LPMF) module file
- * The purpose of this file is to define the Multinomial LPMF class and its fields
- * and return the log probability mass function.
- *
+/**
+ * @file multinomial_lpmf.hpp
+ * @brief Multinomial Log Probability Mass Function (LPMF) module file defines
+ * the Multinomial LPMF class and its fields and returns the log probability
+ * mass function.
+ * @copyright This file is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the source
+ * folder for reuse information.
  */
-
 #ifndef MULTINOMIAL_LPMF
 #define MULTINOMIAL_LPMF
 

inst/include/distributions/functors/normal_lpdf.hpp

@@ -1,14 +1,11 @@
-/*
- * File:   normal_lpdf.hpp
- *
- * This File is part of the NOAA, National Marine Fisheries Service
- * Fisheries Integrated Modeling System project. See LICENSE in the
- * source folder for reuse information.
- *
- * Normal Log Probability Density Function (LPDF) module file
- * The purpose of this file is to define the Normal LPDF class and its fields
- * and return the log probability density function.
- *
+/**
+ * @file normal_lpdf.hpp
+ * @brief Normal Log Probability Density Function (LPDF) module file defines
+ * the Normal LPDF class and its fields and returns the log probability density
+ * function.
+ * @copyright This file is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the source
+ * folder for reuse information.
  */
 
 #ifndef NORMAL_LPDF

inst/include/interface/init.hpp

@@ -1,3 +1,10 @@
+/**
+ * @file init.hpp
+ * @brief TODO: provide a brief description.
+ * @copyright This file is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the source
+ * folder for reuse information.
+ */
 #ifndef INTERFACE_INIT_HPP
 #define INTERFACE_INIT_HPP
 #include <R_ext/Rdynload.h>
@@ -23,14 +30,40 @@
   }
 #endif
 
+/**
+ * @brief TODO: provide a brief description.
+ * 
+ */
 #define CALLDEF(name, n) \
   { #name, (DL_FUNC)&name, n }
 
 extern "C" {
 
+/**
+ * @brief TODO: provide a brief description.
+ * 
+ * @param mean 
+ * @param nu 
+ * @return SEXP 
+ */
 SEXP compois_calc_var(SEXP mean, SEXP nu);
+/**
+ * @brief TODO: provide a brief description.
+ * 
+ * @return SEXP 
+ */
 SEXP omp_check();
+/**
+ * @brief TODO: provide a brief description.
+ * 
+ * @return SEXP 
+ */
 SEXP omp_num_threads(SEXP);
+/**
+ * @brief TODO: provide a brief description.
+ * 
+ * @return SEXP 
+ */
 SEXP _rcpp_module_boot_fims();
 
 /**
@@ -46,7 +79,7 @@ static const R_CallMethodDef CallEntries[] = {
 /**
  *
  * FIMS shared object initializer.
- * @param dll
+ * @param dll TODO: provide a brief description.
  *
  */
 void R_init_FIMS(DllInfo *dll) {

inst/include/interface/interface.hpp

@@ -1,10 +1,9 @@
-/*
- * File: interface.hpp
- *
- * This File is part of the NOAA, National Marine Fisheries Service
- * Fisheries Integrated Modeling System project.
- * Refer to the LICENSE file for reuse information.
- *
+/**
+ * @file interface.hpp
+ * @brief TODO: provide a brief description.
+ * @copyright This file is part of the NOAA, National Marine Fisheries Service
+ * Fisheries Integrated Modeling System project. See LICENSE in the source
+ * folder for reuse information.
  */
 
 #ifndef FIMS_INTERFACE_HPP
@@ -57,8 +56,20 @@ vector<Type> ADREPORTvector(vector<vector<Type> > x) {
 #endif /* TMB_MODEL */
 
 #ifndef TMB_MODEL
+ /**
+  * @brief TODO: provide a brief description.
+  * 
+  */
  #define FIMS_SIMULATE_F(F)
+ /**
+  * @brief TODO: provide a brief description.
+  * 
+  */
  #define FIMS_REPORT_F(name, F)
+ /**
+  * @brief TODO: provide a brief description.
+  * 
+  */
  #define ADREPORT_F(name, F)
 #endif