Merge pull request #890 from AVSLab/feature/doxygen_warning

Treat doxygen warnings as errors

docs/source/Support/bskReleaseNotes.rst

@@ -106,6 +106,8 @@ Version  |release|
 - :ref:`simIncludeGravBody` set the moon equatorial radius in km, not meters.
 - fixed ``subMRP()`` routine in :ref:`RigidBodyKinematics`
 - Updated :ref:`solarArrayReference` to correct the wrong assumption of reflective solar arrays for momentum management pointing mode.
+- Updated the CI build that includes the documentation to fail if a doxygen warning happens
+- Removed deprecated swig code that allowed still importing `sys_model.h` instead of `sys_model.i`
 
 
 Version 2.5.0 (Sept. 30, 2024)

docs/source/conf.py

@@ -121,6 +121,11 @@
     'breathe'
 ]
 
+breathe_doxygen_config_options = {
+    'WARN_AS_ERROR': 'YES'
+    , 'WARN_IF_UNDOCUMENTED': 'YES'  # Ensure undocumented variables, functions, etc., raise warnings
+}
+
 # Add any paths that contain templates here, relative to this directory.
 #templates_path = ['_templates']
 

src/architecture/_GeneralModuleFiles/sys_model.h

@@ -29,7 +29,16 @@ class SysModel
 {
 public:
     SysModel();
-    SysModel(const SysModel &obj); //!< constructor definition
+
+    /**
+     * @brief Copy constructor for SysModel.
+     *
+     * This constructor initializes a new SysModel instance by copying data
+     * from another SysModel instance.
+     *
+     * @param obj The SysModel object to copy data from.
+     */
+    SysModel(const SysModel &obj);
 
     virtual ~SysModel(){};
 
@@ -45,27 +54,11 @@ class SysModel
     /** Called at simulation initialization, resets module to specified time */
     virtual void Reset(uint64_t CurrentSimNanos){};
 
-    std::string ModelTag = "";     //!< -- name for the algorithm to base off of
-    uint64_t CallCounts = 0;       //!< -- Counts on the model being called
-    uint32_t RNGSeed = 0x1badcad1; //!< -- Giving everyone a random seed for ease of MC
-    int64_t moduleID;              //!< -- Module ID for this module  (handed out by module_id_generator)
+    std::string ModelTag = "";     //!< Basilisk module tag name
+    uint64_t CallCounts = 0;       //!< Counts on the model being called
+    uint32_t RNGSeed = 0x1badcad1; //!< Giving everyone a random seed for ease of MC
+    int64_t moduleID;              //!< Module ID for this module  (handed out by module_id_generator)
 };
 
-// The following code helps users who defined their own module classes
-// to transition to using the SWIG file for sys_model instead of the header file.
-// After a period of 12 months from 2023/09/15, this message can be removed.
-#ifdef SWIG
-%extend SysModel
-{
-    %pythoncode %{
-        def logger(self, *args, **kwargs):
-            raise TypeError(
-                f"The 'logger' function is not supported for this type ('{type(self).__qualname__}'). "
-                "To fix this, update the SWIG file for this module. Change "
-                """'%include "sys_model.h"' to '%include "sys_model.i"'"""
-            )
-    %}
-}
-#endif
 
 #endif /* _SYS_MODEL_H_ */

src/architecture/system_model/sim_model.cpp

@@ -63,7 +63,6 @@ SimThreadExecution::SimThreadExecution(uint64_t threadIdent, uint64_t currentSim
 /*! This method provides a synchronization mechanism for the "child" thread
     ensuring that it can be held at a fixed point after it finishes the
     execution of a given frame until it is released by the "parent" thread.
- @return void
  */
 void SimThreadExecution::lockThread() {
     this->selfThreadLock.acquire();
@@ -72,7 +71,6 @@ void SimThreadExecution::lockThread() {
 /*! This method provides a forced synchronization on the "parent" thread so that
     the parent and all other threads in the system can be forced to wait at a
     known time until this thread has finished its execution for that time.
- @return void
  */
 void SimThreadExecution::lockParent() {
     this->parentThreadLock.acquire();
@@ -81,7 +79,6 @@ void SimThreadExecution::lockParent() {
 /*! This method provides an entry point for the "parent" thread to release the
     child thread for a single frame's execution.  It is intended to only be
     called from the parent thread.
- @return void
  */
 void SimThreadExecution::unlockThread() {
     this->selfThreadLock.release();
@@ -91,7 +88,6 @@ void SimThreadExecution::unlockThread() {
     parent thread after it has finished its execution in a frame.  That way the
     parent and all of its other children have to wait for this child to finish
     its execution.
- @return void
  */
 void SimThreadExecution::unlockParent() {
     this->parentThreadLock.release();
@@ -101,7 +97,6 @@ void SimThreadExecution::unlockParent() {
     increments the internal simulation time appropriately as the simulation
     processes are triggered
     @param stopPri The priority level below which the sim won't go
-    @return void
 */
 void SimThreadExecution::SingleStepProcesses(int64_t stopPri)
 {
@@ -138,7 +133,6 @@ void SimThreadExecution::SingleStepProcesses(int64_t stopPri)
 
 /*! This method steps the simulation until the specified stop time and
  stop priority have been reached.
- @return void
  */
 void SimThreadExecution::StepUntilStop()
 {
@@ -159,7 +153,6 @@ void SimThreadExecution::StepUntilStop()
 /*! This method is currently vestigial and needs to be populated once the message
     sharing process between different threads is handled.
     TODO: Make this method move messages safely between threads
- @return void
  */
 void SimThreadExecution::moveProcessMessages() const {
 //    for(auto const& process : this->processList)
@@ -173,7 +166,6 @@ void SimThreadExecution::moveProcessMessages() const {
     their startup before the system starts to go through its initialization
     activities.  It's very similar to the locking process, but provides different
     functionality.
- @return void
  */
 void SimThreadExecution::waitOnInit() {
     std::unique_lock<std::mutex> lck(this->initReadyLock);
@@ -186,7 +178,6 @@ void SimThreadExecution::waitOnInit() {
 /*! This method allows the startup activities to alert the parent thread once
     they have cleared their construction phase and are ready to go through
     initialization.
- @return void
  */
 void SimThreadExecution::postInit() {
     std::unique_lock<std::mutex> lck(this->initReadyLock);
@@ -197,7 +188,6 @@ void SimThreadExecution::postInit() {
 /*! This method is used by the "child" thread to walk through all of its tasks
     and processes and initialize them serially.  Note that other threads can also
     be initializing their systems simultaneously.
- @return void
  */
 void SimThreadExecution::selfInitProcesses() const {
     for(auto const& process : this->processList)
@@ -208,7 +198,6 @@ void SimThreadExecution::selfInitProcesses() const {
 
 /*! This method is vestigial and should probably be removed once MT message
     movement has been completed.
- @return void
  */
 void SimThreadExecution::crossInitProcesses() const {
 //    for(auto const& process : this->processList)
@@ -220,7 +209,6 @@ void SimThreadExecution::crossInitProcesses() const {
 /*! This method allows the "child" thread to reset both its timing/scheduling, as
     well as all of its allocated tasks/modules when commanded.  This is always
     called during init, but can be called during runtime as well.
- @return void
  */
 void SimThreadExecution::resetProcesses() {
     this->currentThreadNanos = 0;
@@ -235,7 +223,6 @@ void SimThreadExecution::resetProcesses() {
 /*! This method pops a new process onto the execution stack for the "child"
     thread.  It allows the user to put specific processes onto specific threads
     if that is desired.
- @return void
  */
 void SimThreadExecution::addNewProcess(SysProcess* newProc) {
     processList.push_back(newProc);
@@ -261,7 +248,6 @@ SimModel::~SimModel()
  stop priority have been reached.
  @param SimStopTime Nanoseconds to step the simulation for
  @param stopPri The priority level below which the sim won't go
- @return void
  */
 void SimModel::StepUntilStop(uint64_t SimStopTime, int64_t stopPri)
 {
@@ -297,7 +283,7 @@ void SimModel::StepUntilStop(uint64_t SimStopTime, int64_t stopPri)
     execution.  Note that the priority level of the process determines what
     order it gets called in: higher priorities are called before lower
     priorities. If priorities are the same, the proc added first goes first.
-    @return void
+
     @param newProc the new process to be added
 */
 void SimModel::addNewProcess(SysProcess *newProc)
@@ -316,7 +302,6 @@ void SimModel::addNewProcess(SysProcess *newProc)
 /*! This method goes through all of the processes in the simulation,
  *  all of the tasks within each process, and all of the models within
  *  each task and self-inits them.
- @return void
  */
 void SimModel::selfInitSimulation()
 {
@@ -336,7 +321,6 @@ void SimModel::selfInitSimulation()
 /*! This method goes through all of the processes in the simulation,
  *  all of the tasks within each process, and all of the models within
  *  each task and resets them.
- @return void
  */
 void SimModel::resetInitSimulation() const
 {
@@ -358,7 +342,6 @@ void SimModel::resetInitSimulation() const
     increments the internal simulation time appropriately as the simulation
     processes are triggered
     @param stopPri The priority level below which the sim won't go
-    @return void
 */
 
 void SimModel::SingleStepProcesses(int64_t stopPri)
@@ -397,7 +380,6 @@ void SimModel::SingleStepProcesses(int64_t stopPri)
 /*! This method is used to reset a simulation to time 0. It sets all process and
  * tasks back to the initial call times. It clears all message logs. However,
  * it does not clear all message buffers and does not reset individual models.
- @return void
  */
 void SimModel::ResetSimulation()
 {
@@ -418,7 +400,7 @@ void SimModel::ResetSimulation()
 /*! This method removes all of the active processes from the "thread pool" that
     has been established.  It is needed during init and if sims are restarted or
     threads need to be reallocated.  Otherwise it is basically a no-op.
- @return void
+
  */
 void SimModel::clearProcsFromThreads() const {
 
@@ -439,7 +421,6 @@ void SimModel::clearProcsFromThreads() const {
     You tell the method how many threads you want in the system, it clears out
     any existing thread data, and then allocates fresh threads for the runtime.
  @param threadCount number of threads
- @return void
  */
 void SimModel::resetThreads(uint64_t threadCount)
 {
@@ -459,7 +440,6 @@ void SimModel::resetThreads(uint64_t threadCount)
     the system, detaches them from the architecture, and then cleans up any
     memory that has been allocated to them in the architecture.  It just ensures
     clean shutdown of any existing runtime stuff.
- @return void
  */
 void SimModel::deleteThreads() {
     for(auto const& simThread : this->threadList)
@@ -479,7 +459,7 @@ void SimModel::deleteThreads() {
     for any processes that haven't already been placed onto a thread.  If the
     user has allocated N threads, this method just walks through those threads
     and pops all of the processes onto those threads in a round-robin fashion.
- @return void
+
  */
 void SimModel::assignRemainingProcs() {
 
@@ -522,7 +502,6 @@ void SimModel::assignRemainingProcs() {
  @param newProc The process that needs to get emplaced on the specified thread
  @param threadSel The thread index in the thread-pool that the process gets added
                   to
- @return void
  */
 void SimModel::addProcessToThread(SysProcess *newProc, uint64_t threadSel)
 {

src/architecture/system_model/sys_model_task.cpp

@@ -32,7 +32,6 @@ SysModelTask::SysModelTask(uint64_t InputPeriod, uint64_t FirstStartTime) :
 }
 
 /*! This method self-initializes all of the models that have been added to the Task.
- @return void
  */
 void SysModelTask::SelfInitTaskList() const
 {
@@ -46,8 +45,7 @@ void SysModelTask::SelfInitTaskList() const
 
 
 /*! This method resets all of the models that have been added to the Task at the CurrentSimTime.
- * See sys_model_task.h for related method ResetTask()
- @return void
+ See sys_model_task.h for related method ResetTask()
  @param CurrentSimTime The time to start at after reset
 */
 void SysModelTask::ResetTaskList(uint64_t CurrentSimTime)
@@ -62,7 +60,6 @@ void SysModelTask::ResetTaskList(uint64_t CurrentSimTime)
 
 /*! This method executes all of the models on the Task during runtime.
  Then, it sets its NextStartTime appropriately.
- @return void
  @param CurrentSimNanos The current simulation time in [ns]
  */
 void SysModelTask::ExecuteTaskList(uint64_t CurrentSimNanos)
@@ -81,7 +78,6 @@ void SysModelTask::ExecuteTaskList(uint64_t CurrentSimNanos)
 
 /*! This method adds a new model into the Task list.  Note that the Priority
  parameter is option as it defaults to -1 (lowest, latest)
- @return void
  @param NewModel The new model that we are adding to the Task
  @param Priority The selected priority of the model being added (highest goes first)
  */
@@ -111,7 +107,6 @@ void SysModelTask::AddNewObject(SysModel *NewModel, int32_t Priority)
 /*! This method changes the period of a given task over to the requested period.
    It attempts to keep the same offset relative to the original offset that
    was specified at task creation.
- @return void
  @param newPeriod The period that the task should run at going forward
  */
 void SysModelTask::updatePeriod(uint64_t newPeriod)

src/architecture/system_model/sys_process.cpp

@@ -23,7 +23,6 @@
 
 /*! Make a process AND attach a storage bucket with the provided name. Give
     the process the same name.
-    @return void
  */
 SysProcess::SysProcess(std::string name) : SysProcess()
 {
@@ -32,7 +31,6 @@ SysProcess::SysProcess(std::string name) : SysProcess()
 
 /*! This method sets the nextTaskTime = 0 and calls SelfInitTaskList() for
  * all process tasks.
- @return void
  */
 void SysProcess::selfInitProcess()
 {
@@ -50,7 +48,6 @@ void SysProcess::selfInitProcess()
 
 /*! This method resets each task and associated model-set inside the process
     ensuring that all parameters go back to their default state.
-    @return void
     @param currentTime Current simulation time in ns that reset is occurring at
 */
 void SysProcess::resetProcess(uint64_t currentTime)
@@ -67,7 +64,6 @@ void SysProcess::resetProcess(uint64_t currentTime)
 /*! This method does two things: 1) resets the next task time for
  *  all process tasks to the first task time. 2) clears the process list
  *  and then adds everything back into the process with the correct priority.
-    @return void
 */
 void SysProcess::reInitProcess()
 {
@@ -87,7 +83,6 @@ void SysProcess::reInitProcess()
 
 /*! This method steps the next task up to currentNanos
  * unless it isn't supposed to run yet.
- @return void
  */
 void SysProcess::singleStepNextTask(uint64_t currentNanos)
 {
@@ -134,7 +129,6 @@ void SysProcess::singleStepNextTask(uint64_t currentNanos)
 
 /*! This method adds a new task into the Task list.  Note that
  * taskPriority parameter is option as it defaults to -1 (lowest)
- @return void
  @param newTask The new task that we are adding to the list
  @param taskPriority The selected priority of the task being added
  */
@@ -154,7 +148,6 @@ void SysProcess::addNewTask(SysModelTask *newTask, int32_t taskPriority)
  place in the simulation schedule.  The transaction for this model is that
  the caller will set the correct parameters in the calling argument and that
  the simulation will faithfully schedule it.
- @return void
  @param taskCall Pointer to a struct that contains start time and task handle.
  */
 void SysProcess::scheduleTask(const ModelScheduleEntry& taskCall)
@@ -178,7 +171,6 @@ void SysProcess::scheduleTask(const ModelScheduleEntry& taskCall)
 /*! The name kind of says it all right?  It is a shotgun used to disable all of
     a process' tasks.  It is handy for a FSW scheme where you have tons of tasks
     and you are really only turning one on at a time.
-    @return void
 */
 void SysProcess::disableAllTasks() const
 {
@@ -191,7 +183,6 @@ void SysProcess::disableAllTasks() const
 /*! The name kind of says it all right?  It is a shotgun used to enable all of
  a processes tasks.  It is handy for a process that starts out almost entirely
  inhibited but you want to turn it all on at once.
- @return void
  */
 void SysProcess::enableAllTasks() const
 {
@@ -204,7 +195,6 @@ void SysProcess::enableAllTasks() const
 
 /*! This method updates a specified task's period once it locates that task
     in the list.  It will warn the user if a task is not found.
-    @return void
 	@param taskName The name of the task you want to change period of
 	@param newPeriod the new number of nanoseconds you want between calls
 */