diff --git a/doc/doxygen/Doxyfile.in b/doc/doxygen/Doxyfile.in index 407c51db..e192a94a 100644 --- 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:^^" -ALIASES += config_param{3|}="" -ALIASES += end_doc="
NameTypeDescription
`\1``\2`\3
^^" +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 index 52529f7e..5b3114a3 100644 --- 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 index 1fdc0c39..f12d9280 100644 --- 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 index ea57cec0..a3ddd04d 100644 --- 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 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 index 91291015..9b53e1a6 100644 --- 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 \ No newline at end of file + # 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 index 3820b021..e3fc01d0 100644 --- 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 index 9cb2cc6b..8ea08ec0 100644 --- 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 index 79389fd1..fc4fe1be 100644 --- 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 index d52a1040..e5c18e99 100644 --- 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 index 60b6e36e..66f099ed 100644 --- 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 index 69ccf038..4a31f204 100644 --- 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 index 5b177707..d35a6f92 100644 --- 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 index f26bcfa3..7fd2090e 100644 --- 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 index 786acd47..7104de38 100644 --- 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 index 6e7bdf38..bde3b801 100644 --- 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 index 260dc4bf..54f5d676 100644 --- 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 index b91c5d36..512203e4 100644 --- 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 index 39af4a81..ee78a62c 100644 --- 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 index 39a628e8..74257b7b 100644 --- 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 index eee5cb5e..f4b9d52a 100644 --- 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 index fb4b82aa..8b50185a 100644 --- 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 index 7a1f7856..880c5b4c 100755 --- 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