fix(doc): remove DRY-violating config param tables (#436)

c-dilks · web-flow · commit 0ab87f375529 · 2026-02-02T11:13:31.000-05:00
diff --git a/doc/doxygen/Doxyfile.in b/doc/doxygen/Doxyfile.in
@@ -290,9 +290,7 @@ ALIASES += algo_type_filter="@par Type: Filter^^This algorithm will filter input
 ALIASES += algo_type_transformer="@par Type: Transformer^^This algorithm will change values within input bank(s).^^"
 ALIASES += algo_type_creator="@par Type: Creator^^^^- This algorithm creates new bank(s); \ref created_banks \"click here for a description of all created banks\".^^- See also the return value type of this algorithm's action functions, which may be `struct`s with the same set of variables as the created bank.^^^^"
 # configuration options
-ALIASES += begin_doc_config{1}="\par Configuration Options:^^YAML configuration, which includes the default option values:^^@include \1/Config.yaml ^^Table of options and descriptions:^^<table><tr><th>Name</th><th>Type</th><th>Description</th></tr>"
-ALIASES += config_param{3|}="<tr><td>`\1`</td><td>`\2`</td><td>\3</td></tr>"
-ALIASES += end_doc="</table>^^"
+ALIASES += doc_config{1}="\par Configuration Options:^^YAML configuration, which includes the default option values:^^@include \1/Config.yaml ^^"
 # databases
 ALIASES += rcdb_note="@note This algorithm uses the RCDB. The RCDB is typically used to access quantities such as beam energy. See iguana::RCDBReader for details; you can access this algorithm's RCDBReader instance by calling GetRCDBReader().^^"
 # run functions
@@ -371,7 +369,10 @@ OPTIMIZE_OUTPUT_SLICE  = NO
 #
 # Note see also the list of default file extension mappings.
 
-EXTENSION_MAPPING      =
+# workaround: using Python syntax coloring for YAML files (viz. Config.yaml),
+# since there is no YAML syntax coloring support in Doxygen; this is good
+# enough in most cases
+EXTENSION_MAPPING      = yaml=Python
 
 # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments
 # according to the Markdown format, which allows for more readable
diff --git a/src/iguana/algorithms/clas12/EventBuilderFilter/Algorithm.h b/src/iguana/algorithms/clas12/EventBuilderFilter/Algorithm.h
@@ -7,9 +7,7 @@ namespace iguana::clas12 {
   /// @algo_brief{Filter the particle bank (`REC::Particle`, or similar) bank by PID from the Event Builder}
   /// @algo_type_filter
   ///
-  /// @begin_doc_config{clas12/EventBuilderFilter}
-  /// @config_param{pids | list[int] | list of PDG codes to filter}
-  /// @end_doc
+  /// @doc_config{clas12/EventBuilderFilter}
   class EventBuilderFilter : public Algorithm
   {
 
diff --git a/src/iguana/algorithms/clas12/MatchParticleProximity/Algorithm.h b/src/iguana/algorithms/clas12/MatchParticleProximity/Algorithm.h
@@ -6,10 +6,7 @@ namespace iguana::clas12 {
 
   /// @algo_brief{Simple particle matching by proximity, for example, MC truth-matching}
   /// @algo_type_creator
-  /// @begin_doc_config{clas12/MatchParticleProximity}
-  /// @config_param{bank_a | string | the particle bank to match from}
-  /// @config_param{bank_b | string | the particle bank to match to}
-  /// @end_doc
+  /// @doc_config{clas12/MatchParticleProximity}
   ///
   /// This algorithm matches one particle bank to another, by smallest proximity, where proximity
   /// is the Euclidean distance in (theta,phi) space.
diff --git a/src/iguana/algorithms/clas12/PhotonGBTFilter/Algorithm.h b/src/iguana/algorithms/clas12/PhotonGBTFilter/Algorithm.h
@@ -13,10 +13,7 @@ namespace iguana::clas12 {
   ///
   /// For each photon (labeled the photon of interest or POI), we obtain its intrinsic features (energy, angle, pcal edep, etc.) and features corresponding to its nearest neighbors (angle of proximity, energy difference, etc.). This requires the reading of both the REC::Particle and REC::Calorimeter banks. An input std::vector<float> is produced and passed to the pretrained GBT models, which yield a classification score between 0 and 1. An option variable `threshold` then determines the minimum photon `p-value` to survive the cut.
   ///
-  /// @begin_doc_config{clas12/PhotonGBTFilter}
-  /// @config_param{pass | int | cook type}
-  /// @config_param{threshold | double | minimum value to qualify a photon as "true"}
-  /// @end_doc
+  /// @doc_config{clas12/PhotonGBTFilter}
   class PhotonGBTFilter : public Algorithm
   {
 
diff --git a/src/iguana/algorithms/clas12/PhotonGBTFilter/Config.yaml b/src/iguana/algorithms/clas12/PhotonGBTFilter/Config.yaml
@@ -1,3 +1,5 @@
 clas12::PhotonGBTFilter:
-    pass: 1
-    threshold: 0.78
+  # which cook
+  pass: 1
+  # minimum value to qualify a photon as 'true'
+  threshold: 0.78
diff --git a/src/iguana/algorithms/clas12/SectorFinder/Algorithm.h b/src/iguana/algorithms/clas12/SectorFinder/Algorithm.h
@@ -8,10 +8,7 @@ namespace iguana::clas12 {
   /// @algo_brief{Find the sector for all rows in `REC::Particle`}
   /// @algo_type_creator
   ///
-  /// @begin_doc_config{clas12/SectorFinder}
-  /// @config_param{bank_charged | string | if not `default`, use this bank for sector finding of charged particles}
-  /// @config_param{bank_neutral | string | if not `default`, use this bank for sector finding of neutral particles}
-  /// @end_doc
+  /// @doc_config{clas12/SectorFinder}
   ///
   /// If `bank_charged` and/or `bank_neutral` is default, then all of the following banks are needed, in addition to `REC::Particle`:
   ///
diff --git a/src/iguana/algorithms/clas12/SectorFinder/Config.yaml b/src/iguana/algorithms/clas12/SectorFinder/Config.yaml
@@ -1,9 +1,5 @@
 clas12::SectorFinder:
-
-  ### use the default banks for both charged/neutral particles
+  # if not 'default', use this bank for sector finding of charged particles
   bank_charged: default
+  # if not 'default', use this bank for sector finding of neutral particles
   bank_neutral: default
-
-  ### alternatively, use custom banks; for example:
-  # bank_charged: default            # default bank for charged particles
-  # bank_neutral: REC::Calorimeter   # custom bank for neutral particles
diff --git a/src/iguana/algorithms/clas12/ZVertexFilter/Algorithm.h b/src/iguana/algorithms/clas12/ZVertexFilter/Algorithm.h
@@ -8,9 +8,7 @@ namespace iguana::clas12 {
   /// @algo_brief{Filter a particle bank by cutting on Z Vertex}
   /// @algo_type_filter
   ///
-  /// @begin_doc_config{clas12/ZVertexFilter}
-  /// @config_param{electron_vz | list[double] | lower and upper electron @f$z@f$-vertex cuts; run-range dependent; cuts are not applied to FT electrons (FD and CD only)}
-  /// @end_doc
+  /// @doc_config{clas12/ZVertexFilter}
   class ZVertexFilter : public Algorithm
   {
 
diff --git a/src/iguana/algorithms/clas12/ZVertexFilter/Config.yaml b/src/iguana/algorithms/clas12/ZVertexFilter/Config.yaml
@@ -5,6 +5,9 @@ clas12::ZVertexFilter:
   particle_bank: 'REC::Particle'
 
   # scattered electron cuts
+  # - lower and upper electron z-vertex cuts
+  # - run-range dependent
+  # - cuts are not applied to FT electrons (FD and CD only)
   electron:
 
     # default cuts
diff --git a/src/iguana/algorithms/clas12/rga/FiducialFilterPass1/Algorithm.h b/src/iguana/algorithms/clas12/rga/FiducialFilterPass1/Algorithm.h
@@ -14,13 +14,7 @@ namespace iguana::clas12::rga {
   ///   - `REC::Particle::Traj`, created by algorithm `iguana::clas12::TrajLinker`
   ///   - `REC::Particle::Calorimeter`, created by algorithm `iguana::clas12::CalorimeterLinker`
   ///
-  /// @begin_doc_config{clas12/rga/FiducialFilterPass1}
-  /// @config_param{pass | int | cook type to use for assigning fiducial cuts}
-  /// @config_param{pcal_electron_cut_level | string | cut level for PCAL homogeneous cuts for electrons and positrons, one of: loose, medium, tight}
-  /// @config_param{pcal_photon_cut_level | string | cut level for PCAL homogeneous cuts for photons, one of: loose, medium, tight}
-  /// @config_param{enable_pcal_cuts | int | enable (1) or disable (0) PCAL cuts }
-  /// @config_param{enable_dc_cuts | int | enable (1) or disable (0) DC cuts }
-  /// @end_doc
+  /// @doc_config{clas12/rga/FiducialFilterPass1}
   class FiducialFilterPass1 : public Algorithm
   {
 
diff --git a/src/iguana/algorithms/clas12/rga/FiducialFilterPass2/Algorithm.h b/src/iguana/algorithms/clas12/rga/FiducialFilterPass2/Algorithm.h
@@ -25,18 +25,7 @@ namespace iguana::clas12::rga {
   /// be reading data which lack certain banks. If you use these functions, take a look at all them
   /// to decide which one best suits your use case.
   ///
-  /// @begin_doc_config{clas12/rga/FiducialFilterPass2}
-  /// @config_param{calorimeter.strictness      | int          | calorimeter cut strictness}
-  /// @config_param{forward_tagger.radius       | list[double] | FT allowed radial window (cm)}
-  /// @config_param{forward_tagger.holes_flat   | list[double] | FT circular holes (radius, x, y)}
-  /// @config_param{cvt.edge_layers             | list[int]    | layers to apply the edge>edge_min test to (all); missing layers are treated as pass}
-  /// @config_param{cvt.edge_min                | double       | edge > 0 to ensure tracks inside CVT}
-  /// @config_param{cvt.phi_forbidden_deg       | list[double] | forbidden phi wedges in degrees (open intervals)}
-  /// @config_param{dc.theta_small_deg          | double       | theta boundary (degrees) for the special inbending case}
-  /// @config_param{dc.thresholds_out           | list[double] | outbending thresholds [Region1, Region2, Region3] (cm)}
-  /// @config_param{dc.thresholds_in_smallTheta | list[double] | inbending thresholds when theta < theta_small_deg (cm)}
-  /// @config_param{dc.thresholds_in_largeTheta | list[double] | inbending thresholds when theta >= theta_small_deg (cm)}
-  /// @end_doc
+  /// @doc_config{clas12/rga/FiducialFilterPass2}
   class FiducialFilterPass2 : public Algorithm
   {
       DEFINE_IGUANA_ALGORITHM(FiducialFilterPass2, clas12::rga::FiducialFilterPass2)
diff --git a/src/iguana/algorithms/clas12/rga/FiducialFilterPass2/Config.yaml b/src/iguana/algorithms/clas12/rga/FiducialFilterPass2/Config.yaml
@@ -1,12 +1,16 @@
 clas12::rga::FiducialFilterPass2:
+
+  # calorimeter cuts
   calorimeter:
-    # strictness=1 -> lv,lw >=  9.0 cm
-    # strictness=2 -> lv,lw >= 13.5 cm
-    # strictness=3 -> lv,lw >= 18.0 cm
+    # calorimeter cut strictness
+    #   strictness=1 -> lv,lw >=  9.0 cm
+    #   strictness=2 -> lv,lw >= 13.5 cm
+    #   strictness=3 -> lv,lw >= 18.0 cm
     #
-    # strictness=1 loosely recommended for spin-asymmetries
+    #   strictness=1 loosely recommended for spin-asymmetries
     strictness: 1
 
+  # FT cuts
   forward_tagger:
     # Allowed radial window (cm)
     radius: [8.5, 15.5]
@@ -17,6 +21,7 @@ clas12::rga::FiducialFilterPass2:
         2.30, -6.15, -13.00,
         2.00,  3.70, -6.50 ]
 
+  # CVT cuts
   cvt:
     # Layers to apply the edge>edge_min test to (all). Missing layers are treated as pass.
     edge_layers: [1, 3, 5, 7, 12]
@@ -26,6 +31,7 @@ clas12::rga::FiducialFilterPass2:
     # Example: (25,40), (143,158), (265,280)
     phi_forbidden_deg: [25, 40, 143, 158, 265, 280]
 
+  # DC cuts
   dc:
     # Theta boundary (degrees) for the special inbending case
     theta_small_deg: 10.0
diff --git a/src/iguana/algorithms/example/ExampleAlgorithm/Algorithm.h b/src/iguana/algorithms/example/ExampleAlgorithm/Algorithm.h
@@ -31,10 +31,7 @@ namespace iguana::example {
   ///
   /// Provide a more detailed description of your algorithm here.
   ///
-  /// @begin_doc_config{example/ExampleAlgorithm}
-  /// @config_param{exampleInt | int | an example `integer` configuration parameter}
-  /// @config_param{exampleDouble | double | an example `double` configuration parameter}
-  /// @end_doc
+  /// @doc_config{example/ExampleAlgorithm}
   class ExampleAlgorithm : public Algorithm
   {
 
diff --git a/src/iguana/algorithms/example/ExampleAlgorithm/Config.yaml b/src/iguana/algorithms/example/ExampleAlgorithm/Config.yaml
@@ -3,6 +3,10 @@
 #   files from other algorithms
 # - See also the test configuration files in ../../tests/config and how they
 #   may be accessed in ../../tests/include/TestConfig.h
+# - Please add comments describing each configuration parameter, since this
+#   YAML file will be used in documentation
 example::ExampleAlgorithm:
+  # an example `integer` configuration parameter
   exampleInt: 8
+  # an example `double` configuration parameter
   exampleDouble: 7.5
diff --git a/src/iguana/algorithms/example/ExampleSubclassAlgorithm/Algorithm.h b/src/iguana/algorithms/example/ExampleSubclassAlgorithm/Algorithm.h
@@ -6,6 +6,7 @@ namespace iguana::example {
 
   /// @algo_brief{example demonstrating inheritance from another algorithm}
   /// @algo_type_filter
+  /// @doc_config{example/ExampleSubclassAlgorithm}
   class ExampleSubclassAlgorithm : public clas12::rga::FiducialFilterPass1
   {
       // use `DEFINE_IGUANA_SUBALGORITHM` rather than the usual `DEFINE_IGUANA_ALGORITHM`;
diff --git a/src/iguana/algorithms/example/ExampleSubclassAlgorithm/Config.yaml b/src/iguana/algorithms/example/ExampleSubclassAlgorithm/Config.yaml
@@ -1,8 +1,6 @@
 example::ExampleSubclassAlgorithm:
 
-  ###################################################################################
   # NOTE: config is the same as `rga::FiducialFilterPass1`, but with value changes
-  ###################################################################################
 
   # cut levels for PCAL homogeneous cuts; one of 'loose', 'medium', or 'tight'
   pcal_electron_cut_level: tight # for electrons and positrons
diff --git a/src/iguana/algorithms/physics/DihadronKinematics/Algorithm.h b/src/iguana/algorithms/physics/DihadronKinematics/Algorithm.h
@@ -9,12 +9,7 @@ namespace iguana::physics {
   /// @algo_brief{Calculate semi-inclusive dihadron kinematic quantities defined in `iguana::physics::DihadronKinematicsVars`}
   /// @algo_type_creator
   ///
-  /// @begin_doc_config{physics/DihadronKinematics}
-  /// @config_param{hadron_a_list | list[int] | list of "hadron A" PDGs}
-  /// @config_param{hadron_b_list | list[int] | list of "hadron B" PDGs}
-  /// @config_param{phi_r_method | string | method used to calculate @latex{\phi_R} (see section "phiR calculation methods" below)}
-  /// @config_param{theta_method | string | method used to calculate @latex{\theta} (see section "theta calculation methods" below)}
-  /// @end_doc
+  /// @doc_config{physics/DihadronKinematics}
   ///
   /// Dihadron PDGs will be formed from pairs from `hadron_a_list` and `hadron_b_list`. For example,
   /// if you define:
diff --git a/src/iguana/algorithms/physics/DihadronKinematics/Config.yaml b/src/iguana/algorithms/physics/DihadronKinematics/Config.yaml
@@ -5,9 +5,10 @@ physics::DihadronKinematics:
   particle_bank: 'REC::Particle'
 
   # list of hadrons used to pair dihadrons
+  # - each hadron from `hadron_a_list` will be paired to each hadron from `hadron_b_list`
   hadron_a_list: [ 211 ]
   hadron_b_list: [ -211, 211, 2212 ]
 
-  # calculation methods
+  # calculation methods; see documentation and source code for details
   phi_r_method: RT_via_covariant_kT
   theta_method: hadron_a
diff --git a/src/iguana/algorithms/physics/InclusiveKinematics/Algorithm.h b/src/iguana/algorithms/physics/InclusiveKinematics/Algorithm.h
@@ -8,13 +8,7 @@ namespace iguana::physics {
 
   /// @algo_brief{Calculate inclusive kinematics quantities}
   /// @algo_type_creator
-  /// @begin_doc_config{physics/InclusiveKinematics}
-  /// @config_param{beam_direction | list[double] | beam direction vector}
-  /// @config_param{target_particle | string | target particle}
-  /// @config_param{beam_particle | string | beam particle}
-  /// @config_param{reconstruction | string | kinematics reconstruction method; only `scattered_lepton` is available at this time}
-  /// @config_param{lepton_finder | string | algorithm to find the scattered lepton}
-  /// @end_doc
+  /// @doc_config{physics/InclusiveKinematics}
   /// @rcdb_note
   class InclusiveKinematics : public Algorithm
   {
diff --git a/src/iguana/algorithms/physics/InclusiveKinematics/Config.yaml b/src/iguana/algorithms/physics/InclusiveKinematics/Config.yaml
@@ -7,9 +7,9 @@ physics::InclusiveKinematics:
 
   # beam configuration
   initial_state:
-    - default:
-      beam_direction: [ 0.0, 0.0, 1.0 ]
-      target_particle: proton
+    - default:                          # default run range
+      beam_direction: [ 0.0, 0.0, 1.0 ] # beam direction vector
+      target_particle: proton           # target particle
 
   # kinematics reconstruction method
   method:
diff --git a/src/iguana/algorithms/physics/SingleHadronKinematics/Algorithm.h b/src/iguana/algorithms/physics/SingleHadronKinematics/Algorithm.h
@@ -9,9 +9,7 @@ namespace iguana::physics {
   /// @algo_brief{Calculate semi-inclusive hadron kinematic quantities}
   /// @algo_type_creator
   ///
-  /// @begin_doc_config{physics/SingleHadronKinematics}
-  /// @config_param{hadron_list | list[int] | calculate kinematics for these hadron PDGs}
-  /// @end_doc
+  /// @doc_config{physics/SingleHadronKinematics}
   ///
   /// The output bank `%physics::SingleHadronKinematics` will have the same number of rows as the input particle bank
   /// - we want the output bank to have the same number of rows and ordering as the input
diff --git a/src/iguana/tests/algo_check.rb b/src/iguana/tests/algo_check.rb
@@ -7,14 +7,20 @@
 algo_list += Dir.glob("src/**/AlgorithmSequence.h")
 
 # check for certain docstrings
-algo_list.each do |algo|
-  puts "check docstrings in #{algo}"
+algo_list.each do |algo_header|
+  puts "check docstrings in #{algo_header}"
   # check for `@algo_brief`
-  system "grep -q '@algo_brief' #{algo}"
-  raise "algorithm #{algo} lacks an '@algo_brief' docstring" unless $?.success?
+  system "grep -q -w '@algo_brief' #{algo_header}"
+  raise "algorithm header #{algo_header} lacks an '@algo_brief' docstring" unless $?.success?
   # check for `@algo_type`
-  unless algo.match? /AlgorithmSequence.h/
-    system "grep -q '@algo_type_' #{algo}"
-    raise "algorithm #{algo} lacks an '@algo_type_*' docstring" unless $?.success?
+  unless algo_header.match? /AlgorithmSequence.h/
+    system "grep -q '@algo_type_' #{algo_header}"
+    raise "algorithm header #{algo_header} lacks an '@algo_type_*' docstring" unless $?.success?
+  end
+  # check for `@doc_config`
+  config_file = "#{File.dirname algo_header}/Config.yaml"
+  if File.exist? config_file
+    system "grep -q -w '@doc_config' #{algo_header}"
+    raise "algorithm header #{algo_header} lacks a '@doc_config' docstring; this is needed since the algorithm has a 'Config.yaml' file" unless $?.success?
   end
 end
