improve commenting formatting

Author: refact0r

src/scope/command-line/execution/executors.cpp

@@ -30,12 +30,9 @@ PrimaryScopePipelineExecutor::PrimaryScopePipelineExecutor(
 }
 
 void PrimaryScopePipelineExecutor::ExecutePipeline() {
-    // Results are stored within the pipeline, can also be accessed
-    // via this function call
     this->pipeline_.Run(this->options_.images);
 }
 
-// Will output the values found by this recalibration
 void PrimaryScopePipelineExecutor::OutputResults() {
     // std::vector<float> *&output = this->pipeline_.GetProduct();
     // TODO: something with output

src/scope/command-line/execution/executors.hpp

@@ -1,3 +1,8 @@
+/**
+ * @file executors.hpp
+ * @brief Pipeline executor for the primary SCOPE calibration chain.
+ */
+
 #ifndef SRC_SCOPE_COMMAND_LINE_EXECUTION_EXECUTORS_HPP_
 #define SRC_SCOPE_COMMAND_LINE_EXECUTION_EXECUTORS_HPP_
 
@@ -13,20 +18,34 @@
 
 namespace scope {
 
+/**
+ * Owns and runs the primary SCOPE calibration pipeline
+ * (noise filter -> star centroid -> optimization).
+ */
 class PrimaryScopePipelineExecutor : public found::PipelineExecutor {
  public:
+    /**
+     * Constructs a PrimaryScopePipelineExecutor and assembles its pipeline.
+     *
+     * @param options Parsed recalibration options consumed by the run.
+     * @param noiseFilterAlgorithm Stage that reduces raw frames to one image.
+     * @param starCentroidAlgorithm Stage that extracts star centroids.
+     * @param optimizationAlgorithm Stage that fits camera parameters.
+     */
     explicit PrimaryScopePipelineExecutor(RecalibrationOptions &&options,
                                           std::unique_ptr<NoiseFilterAlgorithm> noiseFilterAlgorithm,
                                           std::unique_ptr<StarCentroidAlgorithm> starCentroidAlgorithm,
                                           std::unique_ptr<OptimizationAlgorithm> optimizationAlgorithm);
 
+    /// Runs the assembled pipeline end-to-end.
     void ExecutePipeline() override;
+    /// Prints the calibrated parameters produced by the pipeline.
     void OutputResults() override;
 
  private:
-    // The options being used by the pipeline
+    /// The options driving this pipeline run.
     const RecalibrationOptions options_;
-    // The primary pipeline for SCOPE operation
+    /// The pipeline assembled for SCOPE operation.
     PrimaryScopePipeline pipeline_;
 };
 

src/scope/command-line/parsing/options.hpp

@@ -34,9 +34,7 @@ SCOPE_CLI_OPTION("input-images", scope::Images, images, {}, scope::strtoimages(o
 
 // NOLINTEND
 
-/**
- * Options object, contains all data requested from user to run all algorithms
- */
+/** Parsed CLI options driving a recalibration run. */
 class RecalibrationOptions {
  public:
 #define SCOPE_CLI_OPTION(name, type, prop, defaultVal, converter, defaultArg,  \

src/scope/command-line/parsing/parser.cpp

@@ -24,12 +24,12 @@ int optind = 2;
 
 namespace scope {
 
-/// For macro processing
+/// Sentinel for options with no default value.
 const char kNoDefaultArgument = 0;
 
 RecalibrationOptions ParseRecalibrationOptions(int argc, char **argv) {
-    // Define an enum for each valid flag (command-line entry), which maps it
-    // from the name to an integer
+    // Each block below re-expands RECALIBRATE to derive a piece of getopt
+    // wiring from the option table in options.hpp.
     enum class ClientOption {
 #define SCOPE_CLI_OPTION(name, type, prop, defaultVal, converter, defaultArg,  \
                          ASSIGN, doc)                                          \
@@ -38,8 +38,6 @@ RecalibrationOptions ParseRecalibrationOptions(int argc, char **argv) {
 #undef SCOPE_CLI_OPTION
     };
 
-    // Define an array of options, which defines the traits pertaining to each
-    // expected command-line entry
     static option long_options[] = {
 #define SCOPE_CLI_OPTION(name, type, prop, defaultVal, converter, defaultArg,  \
                          ASSIGN, doc)                                          \
@@ -50,15 +48,10 @@ RecalibrationOptions ParseRecalibrationOptions(int argc, char **argv) {
 #undef SCOPE_CLI_OPTION
         {0}};
 
-    // Define our result, and iterator helpers
     RecalibrationOptions options;
     int index;
     int option;
 
-    // Iterates through the list of command-line tokens and figures out
-    // what data to assign to which field in options. Note that the
-    // SCOPE_CLI_OPTION defines the conversion already between any
-    // particular parameter (as a string) to its actual type
     while ((option = getopt_long(argc, argv, "", long_options, &index)) != -1) {
         switch (option) {
 #define SCOPE_CLI_OPTION(name, type, prop, defaultVal, converter, defaultArg,  \

src/scope/command-line/parsing/parser.hpp

@@ -8,14 +8,12 @@ namespace scope {
 #define HELP_MSG "Use ./scope --help or ./scope -h for help"
 
 /**
- * Parses the recalibration options from the command line to
- * run the recalibration algorithm
- * 
- * @param argc The number of command-line arguments
- * @param argv The command line arguments
- * 
- * @return CalibrationOptions The options for the calibration
- * algorithm as extracted on the command line
+ * Parses recalibration flags from the command line.
+ *
+ * @param argc The number of command-line arguments.
+ * @param argv The command-line arguments.
+ *
+ * @return The recalibration options extracted from the command line.
  */
 RecalibrationOptions ParseRecalibrationOptions(int argc, char **argv);
 

src/scope/command-line/scope-main.hpp

@@ -4,17 +4,13 @@
 namespace scope {
 
 /**
- * This is where the program starts.
+ * Program entry point. Parses command-line options and runs the
+ * recalibration pipeline.
  *
- * @param argc The number of arguments passed into the command line
- * @param argv The arguments passed into the command line
+ * @param argc The number of command-line arguments.
+ * @param argv The command-line arguments.
  *
- * @return An integer indicating success (0) iff the program executes
- * successfully
- *
- * @note The method itself uses command line arguments to generate
- * an Options object that represents all the algorithms we want to run
- * and their parameters
+ * @return 0 on success, non-zero on failure.
  */
 int main(int argc, char** argv);
 

src/scope/common/style.hpp

@@ -9,16 +9,16 @@
 
 namespace scope {
 
-// Single image from FOUND
+/** Single image from FOUND. */
 typedef found::Image Image;
 
-// Images passed in by the user
+/** Images passed in by the user. */
 typedef std::vector<found::Image> Images;
 
-// Number of (maximum) stages for each pipeline
+/** Number of (maximum) stages for each pipeline. */
 constexpr size_t recalibration_size = 3;
 
-/// Pipeline for Recalibration
+/** Pipeline for Recalibration. */
 typedef found::SequentialPipeline<std::vector<found::Image>, std::vector<float>, recalibration_size>
     PrimaryScopePipeline;
 

src/scope/noise-filter/noise-filter.cpp

@@ -14,7 +14,7 @@ namespace {
 ///
 /// @param images Input images to validate.
 /// @throws std::invalid_argument if the image collection is empty.
-/// @throws std::runtime_error if any image is null, invalid, or mismatched.
+/// @throws std::runtime_error if any image is null or has mismatched dimensions.
 void ValidateInput(const Images& images) {
     if (images.empty()) {
         throw std::invalid_argument(
@@ -47,8 +47,6 @@ void ValidateInput(const Images& images) {
 
 }  // namespace
 
-///// DarkScreenFilter /////
-
 Image DarkScreenFilter::Run(const Images& images) {
     ValidateInput(images);
 

src/scope/noise-filter/noise-filter.hpp

@@ -1,8 +1,7 @@
-/// @file noise-filter.hpp
-/// @brief Noise filtering algorithms for SCOPE calibration.
-///
-/// This header defines the noise-filter pipeline stage: its abstract
-/// base and concrete implementations.
+/**
+ * @file noise-filter.hpp
+ * @brief Noise filtering algorithms for SCOPE calibration.
+ */
 
 #ifndef SRC_SCOPE_NOISE_FILTER_NOISE_FILTER_HPP_
 #define SRC_SCOPE_NOISE_FILTER_NOISE_FILTER_HPP_
@@ -13,25 +12,34 @@
 
 namespace scope {
 
-/// Pipeline stage that reduces a collection of input frames to a single
-/// representative image (e.g. dark frame / fixed-pattern noise estimate).
+/**
+ * Reduces a set of input frames to a single representative image
+ * (e.g. a dark frame / fixed-pattern noise estimate).
+ */
 class NoiseFilterAlgorithm : public found::FunctionStage<Images, Image> {
  public:
     NoiseFilterAlgorithm() = default;
     virtual ~NoiseFilterAlgorithm() {}
 };
 
-/// Computes a per-pixel median filter to estimate fixed-pattern noise.
+/**
+ * Computes a per-pixel median across frames to estimate fixed-pattern noise.
+ */
 class DarkScreenFilter : public NoiseFilterAlgorithm {
  public:
     DarkScreenFilter() = default;
     ~DarkScreenFilter() override = default;
 
-    /// @param images Raw frames with identical dimensions and channel counts.
-    /// @return The median image with newly allocated pixel storage.
-    ///         The caller must free the image buffer.
-    /// @throws std::invalid_argument if images collection is empty.
-    /// @throws std::runtime_error if images have mismatched dimensions.
+    /**
+     * Computes the per-pixel median of the input frames.
+     *
+     * @param images Frames with identical dimensions and channel counts.
+     *
+     * @return The median image; the caller owns the pixel buffer.
+     *
+     * @throws std::invalid_argument if images is empty.
+     * @throws std::runtime_error if any image is null or has mismatched dimensions.
+     */
     Image Run(const Images &images) override;
 };
 

src/scope/optimization/optimization.hpp

@@ -1,8 +1,7 @@
-/// @file optimization.hpp
-/// @brief Parameter-fit optimization algorithms for SCOPE calibration.
-///
-/// This header defines the optimization pipeline stage: its abstract
-/// base and concrete implementations.
+/**
+ * @file optimization.hpp
+ * @brief Parameter-fit optimization algorithms for SCOPE calibration.
+ */
 
 #ifndef SRC_SCOPE_OPTIMIZATION_OPTIMIZATION_HPP_
 #define SRC_SCOPE_OPTIMIZATION_OPTIMIZATION_HPP_
@@ -15,21 +14,38 @@
 
 namespace scope {
 
-/// Pipeline stage that produces updated camera parameters from centroids.
+/**
+ * Produces updated camera intrinsic + distortion parameters from star centroids.
+ */
 class OptimizationAlgorithm : public found::FunctionStage<std::vector<float>, std::vector<float>> {
  public:
     OptimizationAlgorithm() = default;
     virtual ~OptimizationAlgorithm() {}
 };
 
-/// Levenberg-Marquardt parameter optimizer. Stub implementation pending
-/// the real algorithm.
+/**
+ * Levenberg-Marquardt parameter optimizer. Stub pending the real algorithm.
+ */
 class LMAOptimizationAlgorithm : public OptimizationAlgorithm {
  public:
     LMAOptimizationAlgorithm() = default;
+
+    /**
+     * Constructs a new LMAOptimizationAlgorithm.
+     *
+     * @param options Parsed recalibration options (currently unused).
+     */
     explicit LMAOptimizationAlgorithm([[maybe_unused]] const RecalibrationOptions &options) {}
+
     ~LMAOptimizationAlgorithm() override = default;
 
+    /**
+     * Fits camera parameters to the given star centroids.
+     *
+     * @param stars Flattened centroid coordinates from the previous stage.
+     *
+     * @return The updated camera parameter vector. The stub returns an empty vector.
+     */
     std::vector<float> Run(const std::vector<float> &stars) override;
 };