docs: Restore doxygen warnings as errors (acts-project#3033)

I think I broke this at some point. This should restore the failure.

I have fixes for the warnings in the pipeline.

Core/include/Acts/Geometry/TrackingVolume.hpp

@@ -309,7 +309,6 @@ class TrackingVolume : public Volume {
   ///
   /// @param visitor The callable. Will be called for each reachable volume
   /// that is found, a selection of the volumes can be done in the visitor
-  /// @param restrictToSensitives If true, only sensitive surfaces are visited
   ///
   /// @note If a context is needed for the visit, the vistitor has to provide
   /// this, e.g. as a private member

Core/include/Acts/MagneticField/MagneticFieldProvider.hpp

@@ -18,6 +18,8 @@
 
 namespace Acts {
 
+/// @defgroup MagneticField Magnetic field
+
 /// Base class for all magnetic field providers
 class MagneticFieldProvider {
  public:

Core/include/Acts/Material/Material.hpp

@@ -17,6 +17,7 @@
 namespace Acts {
 
 /// Material description for interactions with matter.
+/// @defgroup Material Material
 ///
 /// The following parameters are used to specify the material and its
 /// interactions with traversing particles:

Core/include/Acts/Propagator/StandardAborters.hpp

@@ -37,7 +37,6 @@ struct PathLimitReached {
   ///
   /// @param [in,out] state The propagation state object
   /// @param [in] stepper Stepper used for propagation
-  /// @param [in] navigator Navigator used for propagation
   /// @param logger a logger instance
   template <typename propagator_state_t, typename stepper_t,
             typename navigator_t>

Core/include/Acts/Utilities/Logger.hpp

@@ -23,6 +23,8 @@
 #include <thread>
 #include <utility>
 
+/// @defgroup Logging Logging
+
 // clang-format off
 /// @brief macro to use a local Acts::Logger object
 /// @ingroup Logging

Core/include/Acts/Vertexing/AdaptiveGridDensityVertexFinder.hpp

@@ -110,8 +110,6 @@ class AdaptiveGridDensityVertexFinder final : public IVertexFinder {
   /// @brief Constructor for user-defined InputTrack type
   ///
   /// @param cfg Configuration object
-  /// @param func Function extracting BoundTrackParameters from InputTrack
-  ///             object
   AdaptiveGridDensityVertexFinder(const Config& cfg) : m_cfg(cfg) {}
 
  private:

Core/include/Acts/Vertexing/FullBilloirVertexFitter.hpp

@@ -83,9 +83,8 @@ class FullBilloirVertexFitter {
   /// @brief Fit method, fitting vertex for provided tracks with constraint
   ///
   /// @param paramVector Vector of track objects to fit vertex to
-  /// @param linearizer The track linearizer
   /// @param vertexingOptions Vertexing options
-  /// @param state The state object
+  /// @param fieldCache The magnetic field cache
   ///
   /// @return Fitted vertex
   Result<Vertex> fit(const std::vector<InputTrack>& paramVector,

Core/include/Acts/Vertexing/GaussianGridTrackDensity.hpp

@@ -31,11 +31,11 @@ class GaussianGridTrackDensity {
     /// @param zMinMax_ The minimum and maximum z-values (in mm) that
     ///                 should be covered by the main 1-dim density grid along
     ///                 the z-axis
-    /// @tparam mainGridSize The size of the z-axis 1-dim main density grid
-    /// @tparam trkGridSize The 2(!)-dim grid size of a single track, i.e.
+    /// @param mainGridSize_ The size of the z-axis 1-dim main density grid
+    /// @param trkGridSize_ The 2(!)-dim grid size of a single track, i.e.
     /// a single track is modelled as a (trkGridSize x trkGridSize) grid
     /// in the d0-z0 plane. Note: trkGridSize has to be an odd value.
-    /// @note The value of @p zMinMax_ together with @p mainGridSize determines the
+    /// @note The value of @p zMinMax_ together with @p mainGridSize_ determines the
     /// overall bin size to be used as seen below
     Config(float zMinMax_ = 100, int mainGridSize_ = 2000,
            int trkGridSize_ = 15)

Core/include/Acts/Vertexing/GaussianTrackDensity.hpp

@@ -113,8 +113,6 @@ class GaussianTrackDensity {
   ///
   /// @param state The track density state
   /// @param trackList All input tracks
-  /// @param extractParameters Function extracting BoundTrackParameters from
-  /// InputTrack
   ///
   /// @return Pair of position of global maximum and Gaussian width
   Result<std::optional<std::pair<double, double>>> globalMaximumWithWidth(
@@ -124,8 +122,6 @@ class GaussianTrackDensity {
   ///
   /// @param state The track density state
   /// @param trackList All input tracks
-  /// @param extractParameters Function extracting BoundTrackParameters from
-  /// InputTrack
   ///
   /// @return z position of the global maximum
   Result<std::optional<double>> globalMaximum(
@@ -139,8 +135,6 @@ class GaussianTrackDensity {
   ///
   /// @param state The track density state
   /// @param trackList All input tracks
-  /// @param extractParameters Function extracting BoundTrackParameters from
-  /// InputTrack
   Result<void> addTracks(State& state,
                          const std::vector<InputTrack>& trackList) const;
 

Core/include/Acts/Vertexing/GridDensityVertexFinder.hpp

@@ -117,8 +117,6 @@ class GridDensityVertexFinder final : public IVertexFinder {
   /// @brief Constructor for user-defined InputTrack type
   ///
   /// @param cfg Configuration object
-  /// @param func Function extracting BoundTrackParameters from InputTrack
-  ///             object
   GridDensityVertexFinder(const Config& cfg) : m_cfg(cfg) {
     if (!m_cfg.extractParameters.connected()) {
       throw std::invalid_argument(

Core/include/Acts/Vertexing/IterativeVertexFinder.hpp

@@ -63,7 +63,6 @@ class IterativeVertexFinder final : public IVertexFinder {
     /// @brief Config constructor
     ///
     /// @param fitter Vertex fitter
-    /// @param lin Track linearizer
     /// @param sfinder The seed finder
     /// @param est ImpactPointEstimator
     Config(VertexFitter fitter, std::shared_ptr<IVertexFinder> sfinder,

Core/include/Acts/Vertexing/TrackDensityVertexFinder.hpp

@@ -66,8 +66,6 @@ class TrackDensityVertexFinder final : public IVertexFinder {
   /// @brief Constructor for user-defined InputTrack type
   ///
   /// @param cfg Configuration object
-  /// @param func Function extracting BoundTrackParameters from InputTrack
-  ///             object
   TrackDensityVertexFinder(const Config& cfg) : m_cfg(cfg) {}
 
  private:

Plugins/Geant4/include/Acts/Plugins/Geant4/Geant4SurfaceProvider.hpp

@@ -83,8 +83,9 @@ class Geant4SurfaceProvider : public Acts::Experimental::ISurfacesProvider {
   };
 
   /// Constructor
-  ///@param config The configuration struct
-  ///@param options The optional configuration for KDTree
+  /// @param config The configuration struct
+  /// @param options The optional configuration for KDTree
+  /// @param validateGDMLschema Whether to validate the gdml schema
   Geant4SurfaceProvider(const Config& config,
                         const kdtOptions& options = kdtOptions(),
                         bool validateGDMLschema = true) {

Plugins/Json/include/Acts/Plugins/Json/VolumeJsonConverter.hpp

@@ -9,6 +9,7 @@
 #pragma once
 
 #include "Acts/Geometry/TrackingVolume.hpp"
+#include "Acts/Material/IVolumeMaterial.hpp"
 #include "Acts/Plugins/Json/ActsJson.hpp"
 
 #include <memory>
@@ -24,18 +25,12 @@ namespace Acts {
 class IVolumeMaterial;
 class TrackingVolume;
 
-using TrackingVolumePointer = const Acts::TrackingVolume*;
-using TrackingVolumeAndMaterial =
-    std::pair<const Acts::TrackingVolume*,
-              std::shared_ptr<const Acts::IVolumeMaterial>>;
-
 /// Conversion of a pair of tracking volume and material used for the material
 /// mapping
-void to_json(nlohmann::json& j, const TrackingVolumeAndMaterial& volume);
-
-/// Conversion of a const pointer on a tracking volume used to write the
-/// geometry
-void to_json(nlohmann::json& j, const TrackingVolumePointer& volume);
+void to_json(
+    nlohmann::json& j,
+    const std::pair<const Acts::TrackingVolume*,
+                    std::shared_ptr<const Acts::IVolumeMaterial>>& volume);
 
 /// Conversion of a tracking volume
 void to_json(nlohmann::json& j, const Acts::TrackingVolume& volume);

Plugins/Json/src/VolumeJsonConverter.cpp

@@ -12,17 +12,14 @@
 #include "Acts/Plugins/Json/GeometryJsonKeys.hpp"
 #include "Acts/Plugins/Json/MaterialJsonConverter.hpp"
 
-void Acts::to_json(nlohmann::json& j,
-                   const Acts::TrackingVolumeAndMaterial& volume) {
+void Acts::to_json(
+    nlohmann::json& j,
+    const std::pair<const Acts::TrackingVolume*,
+                    std::shared_ptr<const Acts::IVolumeMaterial>>& volume) {
   j[Acts::jsonKey().namekey] = volume.first->volumeName();
   to_json(j, volume.second.get());
 }
 
-void Acts::to_json(nlohmann::json& j,
-                   const Acts::TrackingVolumePointer& volume) {
-  to_json(j, *volume);
-}
-
 void Acts::to_json(nlohmann::json& j, const Acts::TrackingVolume& volume) {
   j[Acts::jsonKey().namekey] = volume.volumeName();
   if (volume.volumeMaterial() != nullptr) {

docs/conf.py

@@ -136,7 +136,6 @@
 # -- Automatic API documentation ---------------------------------------------
 
 env = os.environ.copy()
-env["DOXYGEN_WARN_AS_ERROR"] = "NO"
 
 if on_readthedocs or tags.has("run_doxygen"):
     # if we are running on RTD Doxygen must be run as part of the build