Doxygen CI: Warnings as Error (#3560)

Make sure that no Doxygen warnings get in, as we do in other CI runs
already.

Depends on AMReX-Codes/amrex#3061

---------

Co-authored-by: Edoardo Zoni <[email protected]>
Co-authored-by: Edoardo Zoni <[email protected]>
Co-authored-by: David Grote <[email protected]>

Author: 3 people

.github/workflows/source.yml

@@ -33,5 +33,6 @@ jobs:
       run: .github/workflows/source/check_inputs.py
     - name: Doxygen
       run: |
-        sudo apt-get install -y --no-install-recommends doxygen
+        sudo apt update
+        sudo apt install -y doxygen texlive-latex-base texlive-latex-extra ghostscript
         .github/workflows/source/doxygen

.github/workflows/source/doxygen

@@ -1,15 +1,27 @@
 #!/usr/bin/env bash
 #
-# Copyright 2020 Axel Huebl
+# Copyright 2020-2023 The WarpX Community
 #
 # License: BSD-3-Clause-LBNL
-
-# search recursive inside a folder if a file contains tabs
-#
-# @result 0 if no files are found, else 1
-#
+# Authors: Axel Huebl
 
 set -eu -o pipefail
 
 cd Docs
+
+curl -L -o amrex-doxygen-web.tag.xml \
+  https://amrex-codes.github.io/amrex/docs_xml/doxygen/amrex-doxygen-web.tag.xml
+
+curl -L -o openpmd-api-doxygen-web.tag.xml \
+  https://openpmd-api.readthedocs.io/en/latest/_static/doxyhtml/openpmd-api-doxygen-web.tag.xml
+
+# Treat all warnings as errors
+if ! grep -q "WARN_AS_ERROR = YES" Doxyfile; then
+    # Add line with the comment
+    echo "" >> Doxyfile
+    echo "# Overwrite value of WARN_AS_ERROR" >> Doxyfile
+    echo "WARN_AS_ERROR = YES" >> Doxyfile
+fi
+
+# Run doxygen
 doxygen

Docs/Doxyfile

@@ -2710,3 +2710,6 @@ GENERATE_LEGEND        = YES
 # The default value is: YES.
 
 DOT_CLEANUP            = YES
+
+# Overwrite value of WARN_AS_ERROR
+WARN_AS_ERROR = YES

Source/BoundaryConditions/PEC_Insulator.H

@@ -91,18 +91,12 @@ public:
      * \param[in]     a_Fz_x_lo the parser for the tangential field at the boundary
      * \param[in]     a_Fy_x_hi the parser for the tangential field at the boundary
      * \param[in]     a_Fz_x_hi the parser for the tangential field at the boundary
-     * \param[in]     set_F_y_lo whether the tangential field at the boundary was specified
-     * \param[in]     set_F_y_hi whether the tangential field at the boundary was specified
-     * \param[in]     a_Fx_y_lo the parser for the tangential field at the boundary
-     * \param[in]     a_Fz_y_lo the parser for the tangential field at the boundary
-     * \param[in]     a_Fx_y_hi the parser for the tangential field at the boundary
-     * \param[in]     a_Fz_y_hi the parser for the tangential field at the boundary
-     * \param[in]     set_F_z_lo whether the tangential field at the boundary was specified
-     * \param[in]     set_F_z_hi whether the tangential field at the boundary was specified
-     * \param[in]     a_Fx_z_lo the parser for the tangential field at the boundary
-     * \param[in]     a_Fy_z_lo the parser for the tangential field at the boundary
-     * \param[in]     a_Fx_z_hi the parser for the tangential field at the boundary
-     * \param[in]     a_Fy_z_hi the parser for the tangential field at the boundary
+     * \\param[in]     set_F_z_lo whether the tangential field at the boundary was specified
+     * \\param[in]     set_F_z_hi whether the tangential field at the boundary was specified
+     * \\param[in]     a_Fx_z_lo the parser for the tangential field at the boundary
+     * \\param[in]     a_Fy_z_lo the parser for the tangential field at the boundary
+     * \\param[in]     a_Fx_z_hi the parser for the tangential field at the boundary
+     * \\param[in]     a_Fy_z_hi the parser for the tangential field at the boundary
      */
     void
     ApplyPEC_InsulatortoField (std::array<amrex::MultiFab*, 3> field,

Source/BoundaryConditions/WarpX_PEC.H

@@ -21,13 +21,13 @@ namespace PEC {
      * \param[in,out] Efield              Boundary values of tangential Efield are set to zero
      * \param[in]     field_boundary_lo   Boundary types of the "low" boundaries
      * \param[in]     field_boundary_hi   Boundary types of the "high" boundaries
+     * \param[in]     bc_type             Boundary condition type to be applied
      * \param[in]     ng_fieldgather      number of guard cells used by field gather
      * \param[in]     geom                geometry object of level "lev"
      * \param[in]     lev                 level of the Multifab
      * \param[in]     patch_type          coarse or fine
      * \param[in]     ref_ratios          vector containing the refinement ratios of the refinement levels
-     * \param[in]     split_pml_field     whether pml the multifab is the regular Efield or
-     *                                        split pml field
+     * \param[in]     split_pml_field     whether the MultiFab is the regular Efield or the split PML field
      */
     void ApplyPECtoEfield (
                         std::array<amrex::MultiFab*, 3> Efield,
@@ -45,11 +45,13 @@ namespace PEC {
      * \param[in,out] Bfield              Boundary values of normal Bfield are set to zero.
      * \param[in]     field_boundary_lo   Boundary types of the "low" field boundaries
      * \param[in]     field_boundary_hi   Boundary types of the "high" field boundaries
+     * \param[in]     bc_type             Boundary condition type to be applied
      * \param[in]     ng_fieldgather      number of guard cells used by field gather
      * \param[in]     geom                geometry object of level "lev"
      * \param[in]     lev                 level of the Multifab
      * \param[in]     patch_type          coarse or fine
      * \param[in]     ref_ratios          vector containing the refinement ratios of the refinement levels
+     * \param[in]     split_pml_field     whether the MultiFab is the regular Bfield or the split PML field
      */
     void ApplyPECtoBfield (
                         std::array<amrex::MultiFab*, 3> Bfield,

Source/Diagnostics/BTDiagnostics.H

@@ -136,6 +136,7 @@ private:
      *  m_t_lab, and z-positions for the i^th snapshot, i_buffer, and level, lev.
      * \param[in] i_buffer i^th snapshot or buffer
      * \param[in] lev mesh-refinement level for which the field and/or particle buffer data is initialized.
+     * \param[in] restart whether this is called upon restarting a previous simulation
      */
     void InitializeBufferData ( int i_buffer , int lev, bool restart=false) override;
     /** Whether to compute back-tranformed values for field-data.

Source/Diagnostics/BoundaryScrapingDiagnostics.H

@@ -22,6 +22,7 @@ public:
      *
      * @param i index of diagnostics in MultiDiagnostics::alldiags
      * @param name diagnostics name in the inputs file
+     * @param diag_type diagnostics type (e.g., full, back-transformed, time-averaged, etc.)
      */
     BoundaryScrapingDiagnostics (int i, const std::string& name, DiagTypes diag_type);
 

Source/Diagnostics/ComputeDiagFunctors/BackTransformParticleFunctor.H

@@ -24,6 +24,7 @@ struct SelectParticles
     /**
      * \brief Constructor of SelectParticles functor.
      *
+     * @param[in] pc                 WarpX particle container
      * @param[in] a_pti              WarpX particle iterator
      * @param[in] current_z_boost    current z-position of the slice in boosted frame
      * @param[in] old_z_boost        previous z-position of the slice in boosted frame
@@ -78,6 +79,7 @@ struct LorentzTransformParticles
     /**
      * \brief Constructor of the LorentzTransformParticles functor.
      *
+     * @param[in] pc                 WarpX particle container
      * @param[in] a_pti              WarpX particle iterator
      * @param[in] t_boost            time in boosted frame
      * @param[in] dt                 timestep in boosted-frame

Source/Diagnostics/ComputeDiagFunctors/RhoFunctor.H

@@ -19,6 +19,7 @@ public:
      * \param[in] lev level of MultiFab
      * \param[in] crse_ratio coarsening ratio for interpolation of field values
      *                       from simulation MultiFabs to the output MultiFab mf_dst
+     * \param[in] apply_rz_psatd_filter if true, apply RZ filter in spectral space
      * \param[in] species_index Index of species to dump rho per species. This argument
      *                          is optional and defaults to -1 (dump total rho)
      * \param[in] convertRZmodes2cartesian if true, all RZ modes are averaged into one component

Source/Diagnostics/Diagnostics.H

@@ -36,6 +36,7 @@ public:
      *
      * @param i index of diagnostics in MultiDiagnostics::alldiags
      * @param name diagnostics name in the inputs file
+     * @param diag_type diagnostics type (e.g., full, back-transformed, time-averaged, etc.)
      */
     Diagnostics (int i, std::string name, DiagTypes diag_type);
 
@@ -197,6 +198,7 @@ protected:
     /** Initialize m_mf_output vectors and data required to construct the buffers
      * \param[in] i_buffer index of buffer for which the output MultiFab is defined.
      * \param[in] lev level on which the output MultiFab is defined
+     * \param[in] restart whether this is called upon restarting a previous simulation
      */
     virtual void InitializeBufferData (int i_buffer, int lev, bool restart=false) = 0;
     /** Initialize member variables and arrays specific to the diagnostics in the