Add comprehensive Doxygen documentation for task classes, utilities, and performance modules. Configure Doxyfile for extended metadata extraction.

Author: allnes

Doxyfile

@@ -4,9 +4,11 @@ PROJECT_BRIEF          = "Parallel Programming Course"
 
 # Input
 INPUT                  = modules/core/task/include \
-                         modules/core/task/src \
                          modules/core/util/include \
-                         modules/core/util/src
+                         modules/core/util/src \
+                         modules/core/performance/include \
+                         modules/core/runners/include \
+                         modules/core/runners/src
 FILE_PATTERNS          = *.h *.c *.hpp *.cpp
 RECURSIVE              = YES
 
@@ -15,3 +17,11 @@ GENERATE_HTML          = NO
 GENERATE_LATEX         = NO
 GENERATE_XML           = YES
 XML_OUTPUT             = xml
+
+# Docs
+EXTRACT_ALL        = YES
+EXTRACT_PRIVATE    = YES
+EXTRACT_TEMPLATE_PARAMS = YES
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION      = YES
+EXPAND_ONLY_PREDEF   = NO

docs/user_guide/api.rst

@@ -4,5 +4,5 @@ API Reference
 .. toctree::
    :maxdepth: 1
 
-.. doxygenindex::
-   :project: ParallelProgrammingCourse
+.. .. doxygenindex::
+..    :project: ParallelProgrammingCourse

modules/core/performance/include/performance.hpp

@@ -14,13 +14,16 @@
 namespace ppc::core {
 
 struct PerfAttr {
-  // count of task's running
+  /// @brief Number of times the task is run for performance evaluation.
   uint64_t num_running = 5;
+  /// @brief Timer function returning current time in seconds.
+  /// @cond
   std::function<double()> current_timer = [&] { return -1.0; };
+  /// @endcond
 };
 
 struct PerfResults {
-  // measurement of task's time (in seconds)
+  /// @brief Measured execution time in seconds.
   double time_sec = 0.0;
   enum TypeOfRunning : uint8_t { kPipeline, kTaskRun, kNone } type_of_running = kNone;
   constexpr static double kMaxTime = 10.0;
@@ -87,7 +90,8 @@ class Perf {
       throw std::runtime_error(err_msg.str().c_str());
     }
   }
-  // Get performance result structure of the current task
+  /// @brief Retrieves the performance test results.
+  /// @return The latest PerfResults structure.
   PerfResults GetPerfResults() { return perf_results_; }
 
  private:

modules/core/runners/include/runners.hpp

@@ -7,25 +7,39 @@
 
 namespace ppc::core {
 
+/// @brief GTest event listener that checks for unread MPI messages after each test.
+/// @note Used to detect unexpected inter-process communication leftovers.
 class UnreadMessagesDetector : public ::testing::EmptyTestEventListener {
  public:
   UnreadMessagesDetector() = default;
+  /// @brief Called by GTest after a test ends. Checks for unread messages.
   void OnTestEnd(const ::testing::TestInfo& /*test_info*/) override;
 
  private:
 };
 
+/// @brief GTest event listener that prints additional information on test failures in worker processes.
+/// @details Includes MPI rank info in failure output for debugging.
 class WorkerTestFailurePrinter : public ::testing::EmptyTestEventListener {
  public:
+  /// @brief Constructs the listener with a base listener for delegation.
+  /// @param base A shared pointer to another GTest event listener.
   explicit WorkerTestFailurePrinter(std::shared_ptr<::testing::TestEventListener> base) : base_(std::move(base)) {}
+  /// @brief Called after a test ends. Passes call to base listener and prints failures with rank.
   void OnTestEnd(const ::testing::TestInfo& test_info) override;
+  /// @brief Called when a test part fails. Prints MPI rank info along with the failure.
   void OnTestPartResult(const ::testing::TestPartResult& test_part_result) override;
 
  private:
+  /// @brief Prints the MPI rank of the current process to stderr.
   static void PrintProcessRank();
   std::shared_ptr<::testing::TestEventListener> base_;
 };
 
+/// @brief Initializes the testing environment (e.g., MPI, logging).
+/// @param argc Argument count.
+/// @param argv Argument vector.
+/// @return Exit code: 0 for success, non-zero for failure.
 int Init(int argc, char** argv);
 
 }  // namespace ppc::core

modules/core/task/include/task.hpp

@@ -19,16 +19,48 @@ using namespace std::chrono;
 
 namespace ppc::core {
 
-enum TypeOfTask : uint8_t { kALL, kMPI, kOMP, kSEQ, kSTL, kTBB, kUnknown };
-enum StatusOfTask : uint8_t { kEnabled, kDisabled };
+/// @brief Represents the type of task (parallelization technology).
+/// @details Used to select the implementation type in tests and execution logic.
+enum TypeOfTask : uint8_t {
+  /// Use all available implementations
+  kALL,
+  /// MPI (Message Passing Interface)
+  kMPI,
+  /// OpenMP (Open Multi-Processing)
+  kOMP,
+  /// Sequential implementation
+  kSEQ,
+  /// Standard Thread Library (STL threads)
+  kSTL,
+  /// Intel Threading Building Blocks (TBB)
+  kTBB,
+  /// Unknown task type
+  kUnknown
+};
+
+/// @brief Indicates whether a task is enabled or disabled.
+enum StatusOfTask : uint8_t {
+  /// Task is enabled and should be executed
+  kEnabled,
+  /// Task is disabled and will be skipped
+  kDisabled
+};
 
+/// @brief Returns a string representation of the task status.
+/// @param status_of_task Task status (enabled or disabled).
+/// @return "enabled" if the task is enabled, otherwise "disabled".
 inline std::string GetStringTaskStatus(StatusOfTask status_of_task) {
   if (status_of_task == kDisabled) {
     return "disabled";
   }
   return "enabled";
 }
 
+/// @brief Returns a string representation of the task type based on the JSON settings file.
+/// @param type_of_task Type of the task.
+/// @param settings_file_path Path to the JSON file containing task type strings.
+/// @return Formatted string combining the task type and its corresponding value from the file.
+/// @throws std::runtime_error If the file cannot be opened.
 inline std::string GetStringTaskType(TypeOfTask type_of_task, const std::string &settings_file_path) {
   std::ifstream file(settings_file_path);
   if (!file.is_open()) {
@@ -65,20 +97,24 @@ inline std::string GetStringTaskType(TypeOfTask type_of_task, const std::string
 
 enum StateOfTesting : uint8_t { kFunc, kPerf };
 
-// Memory of inputs and outputs need to be initialized before create an object of
-// Task class
 template <typename InType, typename OutType>
+/// @brief Base abstract class representing a generic task with a defined pipeline.
+/// @tparam InType Input data type.
+/// @tparam OutType Output data type.
 class Task {
  public:
+  /// @brief Constructs a new Task object.
   explicit Task(StateOfTesting /*state_of_testing*/ = StateOfTesting::kFunc) { functions_order_.clear(); }
 
-  // validation of data and validation of task attributes before running
+  /// @brief Validates input data and task attributes before execution.
+  /// @return True if validation is successful.
   virtual bool Validation() final {
     InternalOrderTest(__builtin_FUNCTION());
     return ValidationImpl();
   }
 
-  // pre-processing of input data
+  /// @brief Performs preprocessing on the input data.
+  /// @return True if preprocessing is successful.
   virtual bool PreProcessing() final {
     InternalOrderTest(__builtin_FUNCTION());
     if (state_of_testing_ == StateOfTesting::kFunc) {
@@ -87,13 +123,15 @@ class Task {
     return PreProcessingImpl();
   }
 
-  // realization of the current task
+  /// @brief Executes the main logic of the task.
+  /// @return True if execution is successful.
   virtual bool Run() final {
     InternalOrderTest(__builtin_FUNCTION());
     return RunImpl();
   }
 
-  // post-processing of output data
+  /// @brief Performs postprocessing on the output data.
+  /// @return True if postprocessing is successful.
   virtual bool PostProcessing() final {
     InternalOrderTest(__builtin_FUNCTION());
     if (state_of_testing_ == StateOfTesting::kFunc) {
@@ -102,25 +140,36 @@ class Task {
     return PostProcessingImpl();
   }
 
-  // get state of testing
+  /// @brief Returns the current testing mode.
+  /// @return Reference to the current StateOfTesting.
   StateOfTesting &GetStateOfTesting() { return state_of_testing_; }
 
-  // set a type of task
+  /// @brief Sets the dynamic task type.
+  /// @param type_of_task Task type to set.
   void SetTypeOfTask(TypeOfTask type_of_task) { type_of_task_ = type_of_task; }
 
-  // get a dynamic type of task
+  /// @brief Returns the dynamic task type.
+  /// @return Current dynamic task type.
   [[nodiscard]] TypeOfTask GetDynamicTypeOfTask() const { return type_of_task_; }
 
-  // get a dynamic type of task
+  /// @brief Returns the current task status.
+  /// @return Task status (enabled or disabled).
   [[nodiscard]] StatusOfTask GetStatusOfTask() const { return status_of_task_; }
 
-  // get a static type of task
+  /// @brief Returns the static task type.
+  /// @return Static task type (default: kUnknown).
   static constexpr TypeOfTask GetStaticTypeOfTask() { return TypeOfTask::kUnknown; }
 
+  /// @brief Returns a reference to the input data.
+  /// @return Reference to the task's input data.
   InType &GetInput() { return input_; }
 
+  /// @brief Returns a reference to the output data.
+  /// @return Reference to the task's output data.
   OutType &GetOutput() { return output_; }
 
+  /// @brief Destructor. Verifies that the pipeline was executed in the correct order.
+  /// @note Terminates the program if pipeline order is incorrect or incomplete.
   virtual ~Task() {
     if (!functions_order_.empty() || !was_worked_) {
       std::cerr << "ORDER OF FUNCTIONS IS NOT RIGHT! \n Expected - \"Validation\", \"PreProcessing\", \"Run\", "
@@ -132,6 +181,8 @@ class Task {
   }
 
  protected:
+  /// @brief Verifies the correct order of pipeline method calls.
+  /// @param str Name of the method being called.
   virtual void InternalOrderTest(const std::string &str) final {
     functions_order_.push_back(str);
     if (str == "PostProcessing" && IsFullPipelineStage()) {
@@ -141,6 +192,9 @@ class Task {
     }
   }
 
+  /// @brief Measures execution time between preprocessing and postprocessing steps.
+  /// @param str Name of the method being timed.
+  /// @throws std::runtime_error If execution exceeds the allowed time limit.
   virtual void InternalTimeTest(const std::string &str) final {
     if (str == "PreProcessing") {
       tmp_time_point_ = std::chrono::high_resolution_clock::now();
@@ -162,16 +216,20 @@ class Task {
     }
   }
 
-  // implementation of "Validation" function
+  /// @brief User-defined validation logic.
+  /// @return True if validation is successful.
   virtual bool ValidationImpl() = 0;
 
-  // implementation of "PreProcessing" function
+  /// @brief User-defined preprocessing logic.
+  /// @return True if preprocessing is successful.
   virtual bool PreProcessingImpl() = 0;
 
-  // implementation of "Run" function
+  /// @brief User-defined task execution logic.
+  /// @return True if run is successful.
   virtual bool RunImpl() = 0;
 
-  // implementation of "PostProcessing" function
+  /// @brief User-defined postprocessing logic.
+  /// @return True if postprocessing is successful.
   virtual bool PostProcessingImpl() = 0;
 
  private:
@@ -198,9 +256,17 @@ class Task {
   }
 };
 
+/// @brief Smart pointer alias for Task.
+/// @tparam InType Input data type.
+/// @tparam OutType Output data type.
 template <typename InType, typename OutType>
 using TaskPtr = std::shared_ptr<Task<InType, OutType>>;
 
+/// @brief Constructs and returns a shared pointer to a task with the given input.
+/// @tparam TaskType Type of the task to create.
+/// @tparam InType Type of the input.
+/// @param in Input to pass to the task constructor.
+/// @return Shared pointer to the newly created task.
 template <typename TaskType, typename InType>
 std::shared_ptr<TaskType> TaskGetter(InType in) {
   return std::make_shared<TaskType>(in);

modules/core/util/include/func_test_util.hpp

@@ -31,9 +31,15 @@ concept HasPrintTestParam = requires(TestType value) {
 };
 
 template <typename InType, typename OutType, typename TestType = void>
+/// @brief Base class for running functional tests on parallel tasks.
+/// @tparam InType Type of input data.
+/// @tparam OutType Type of output data.
+/// @tparam TestType Type of the test case or parameter.
 class BaseRunFuncTests : public ::testing::TestWithParam<FuncTestParam<InType, OutType, TestType>> {
  public:
   virtual bool CheckTestOutputData(OutType& output_data) = 0;
+  /// @brief Provides input data for the task.
+  /// @return Initialized input data.
   virtual InType GetTestInputData() = 0;
 
   template <typename Derived>
@@ -79,6 +85,7 @@ class BaseRunFuncTests : public ::testing::TestWithParam<FuncTestParam<InType, O
     return !ppc::util::IsUnderMpirun() && (contains_substring("_all") || contains_substring("_mpi"));
   }
 
+  /// @brief Initializes task instance and runs it through the full pipeline.
   void InitializeAndRunTask(const FuncTestParam<InType, OutType, TestType>& test_param) {
     task_ = std::get<GTestParamIndex::kTaskGetter>(test_param)(GetTestInputData());
 

modules/core/util/include/perf_test_util.hpp

@@ -28,15 +28,20 @@ using PerfTestParam = std::tuple<std::function<ppc::core::TaskPtr<InType, OutTyp
                                  ppc::core::PerfResults::TypeOfRunning>;
 
 template <typename InType, typename OutType>
+/// @brief Base class for performance testing of parallel tasks.
+/// @tparam InType Input data type.
+/// @tparam OutType Output data type.
 class BaseRunPerfTests : public ::testing::TestWithParam<PerfTestParam<InType, OutType>> {
  public:
+  /// @brief Generates a readable name for the performance test case.
   static std::string CustomPerfTestName(const ::testing::TestParamInfo<PerfTestParam<InType, OutType>>& info) {
     return ppc::core::GetStringParamName(std::get<GTestParamIndex::kTestParams>(info.param)) + "_" +
            std::get<GTestParamIndex::kNameTest>(info.param);
   }
 
  protected:
   virtual bool CheckTestOutputData(OutType& output_data) = 0;
+  /// @brief Supplies input data for performance testing.
   virtual InType GetTestInputData() = 0;
 
   virtual void SetPerfAttributes(ppc::core::PerfAttr& perf_attrs) {

modules/core/util/include/util.hpp

@@ -13,9 +13,10 @@
 
 #include <nlohmann/json.hpp>  // NOLINT(misc-include-cleaner)
 
+/// @brief JSON namespace used for settings and config parsing.
 using NlohmannJsonParseError = nlohmann::json::parse_error;  // NOLINT(misc-include-cleaner)
-using NlohmannJsonTypeError = nlohmann::json::type_error;    // NOLINT(misc-include-cleaner)
-
+/// @brief JSON namespace used for settings and config typing.
+using NlohmannJsonTypeError = nlohmann::json::type_error;  // NOLINT(misc-include-cleaner)
 #ifdef _MSC_VER
 #pragma warning(pop)
 #endif