Fix various documentation issues

LICENSE.MIT

@@ -0,0 +1,19 @@
+Copyright (c) <year> <copyright holders>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

include/bout/adios_object.hxx

@@ -1,4 +1,4 @@
-/*!************************************************************************
+/*!\file*******************************************************************
  * Provides access to the ADIOS library, handling initialisation and
  * finalisation.
  *

include/bout/assert.hxx

@@ -1,4 +1,4 @@
-/*!
+/*!\file
  * Defines a macro ASSERT which throws a BoutException if a given
  * condition is false. Whether the assertion is tested depends on
  * the checking level, so assetions can be removed for optimised runs.

include/bout/bout.hxx

@@ -82,6 +82,13 @@
  * either by including boutmain.hxx or by including bout/physicsmodel.hxx
  * and using the BOUTMAIN macro.
  *
+ * Outputs
+ * -------
+ *
+ * Any non-zero return value should halt the simulation. If the return value is
+ * less than zero, the exit status from BOUT++ is 0, otherwise it is the return
+ * value of BoutInitialise.
+ *
  */
 int BoutInitialise(int& argc, char**& argv);
 

include/bout/dcomplex.hxx

@@ -7,12 +7,12 @@
  *
  * 2015-03-09 Ben Dudson <bd512@york.ac.uk>
  *    o Removed, redefined in terms of std::complex
- * 
+ *
  **************************************************************************
  * Copyright 2010 B.D.Dudson, S.Farley, M.V.Umansky, X.Q.Xu
  *
  * Contact: Ben Dudson, bd512@york.ac.uk
- * 
+ *
  * This file is part of BOUT++.
  *
  * BOUT++ is free software: you can redistribute it and/or modify
@@ -27,7 +27,7 @@
  *
  * You should have received a copy of the GNU Lesser General Public License
  * along with BOUT++.  If not, see <http://www.gnu.org/licenses/>.
- * 
+ *
  */
 #ifndef BOUT_DCOMPLEX_H
 #define BOUT_DCOMPLEX_H
@@ -37,7 +37,9 @@
 
 using dcomplex = std::complex<BoutReal>;
 
-const dcomplex Im(0, 1); // 1i
+/// Imaginary unit, ``1i``
+//NOLINTNEXTLINE(readability-identifier-length)
+constexpr dcomplex Im{0, 1};
 
 /// Complex type for passing data to/from FORTRAN
 struct fcmplx {

include/bout/difops.hxx

@@ -1,11 +1,11 @@
 /*!******************************************************************************
  * \file difops.hxx
- * 
+ *
  * Differential operators
  *
  * Changelog:
  *
- * 2009-01 Ben Dudson <bd512@york.ac.uk> 
+ * 2009-01 Ben Dudson <bd512@york.ac.uk>
  *    * Added two optional parameters which can be put in any order
  *      These determine the method to use (DIFF_METHOD)
  *      and CELL_LOC location of the result.
@@ -15,7 +15,7 @@
  * Copyright 2010 B.D.Dudson, S.Farley, M.V.Umansky, X.Q.Xu
  *
  * Contact: Ben Dudson, bd512@york.ac.uk
- * 
+ *
  * This file is part of BOUT++.
  *
  * BOUT++ is free software: you can redistribute it and/or modify
@@ -30,7 +30,7 @@
  *
  * You should have received a copy of the GNU Lesser General Public License
  * along with BOUT++.  If not, see <http://www.gnu.org/licenses/>.
- * 
+ *
  *******************************************************************************/
 
 #ifndef BOUT_DIFOPS_H
@@ -81,7 +81,7 @@ Field3D Grad_parP(const Field3D& apar, const Field3D& f);
  * \f[
  *    v\mathbf{b}_0 \cdot \nabla f
  * \f]
- * 
+ *
  *
  * @param[in] v  The velocity in y direction
  * @param[in] f  The scalar field to be differentiated
@@ -150,9 +150,9 @@ inline Field3D Div_par_flux(const Field3D& v, const Field3D& f, CELL_LOC outloc,
 }
 
 /*!
- * second parallel derivative
+ * Second parallel derivative:
  * \f[
- *    (\mathbf{b} dot \nabla)(\mathbf{b} dot \nabla)
+ *    (\mathbf{b} \cdot \nabla)(\mathbf{b} \cdot \nabla)
  * \f]
  *
  * Note: For parallel Laplacian use LaplacePar
@@ -175,7 +175,7 @@ inline Field3D Grad2_par2(const Field3D& f, CELL_LOC outloc, DIFF_METHOD method)
 
 /*!
  * Parallel divergence of diffusive flux, K*Grad_par
- * 
+ *
  * \f[
  *    \nabla \cdot ( \mathbf{b}_0 kY (\mathbf{b}_0 \cdot \nabla) f )
  * \f]
@@ -199,8 +199,8 @@ Field3D Div_par_K_Grad_par(const Field3D& kY, const Field3D& f,
  * Perpendicular Laplacian operator
  *
  * This version only includes terms in X and Z, dropping
- * derivatives in Y. This is the inverse operation to 
- * the Laplacian inversion class. 
+ * derivatives in Y. This is the inverse operation to
+ * the Laplacian inversion class.
  *
  * For the full perpendicular Laplacian, use Laplace_perp
  */
@@ -212,7 +212,7 @@ FieldPerp Delp2(const FieldPerp& f, CELL_LOC outloc = CELL_DEFAULT, bool useFFT
 /*!
  * Perpendicular Laplacian, keeping y derivatives
  *
- * 
+ *
  */
 Coordinates::FieldMetric
 Laplace_perp(const Field2D& f, CELL_LOC outloc = CELL_DEFAULT,
@@ -246,18 +246,18 @@ Field2D Laplace_perpXY(const Field2D& A, const Field2D& f);
 
 /*!
  * Terms of form b0 x Grad(phi) dot Grad(A)
- * 
+ *
  */
 Coordinates::FieldMetric b0xGrad_dot_Grad(const Field2D& phi, const Field2D& A,
                                           CELL_LOC outloc = CELL_DEFAULT);
 
 /*!
- * Terms of form 
+ * Terms of form
  *
  * \f[
  *   \mathbf{b}_0 \times \nabla \phi \cdot \nabla A
  * \f]
- * 
+ *
  * @param[in] phi The scalar potential
  * @param[in] A   The field being advected
  * @param[in] outloc  The cell location where the result is defined. By default the same as A.
@@ -291,13 +291,13 @@ constexpr BRACKET_METHOD BRACKET_CTU = BRACKET_METHOD::ctu;
  * \f[
  *   [f, g] = (1/B) \mathbf{b}_0 \times \nabla f  \cdot \nabla g
  * \f]
- * 
+ *
  * @param[in] f  The potential
  * @param[in] g  The field being advected
  * @param[in] method   The method to use
  * @param[in] outloc   The cell location where the result is defined. Default is the same as g
  * @param[in] solver   Pointer to the time integration solver
- * 
+ *
  */
 Coordinates::FieldMetric bracket(const Field2D& f, const Field2D& g,
                                  BRACKET_METHOD method = BRACKET_STD,

include/bout/field.hxx

@@ -770,7 +770,7 @@ FIELD_FUNC(exp, ::exp)
 /// Natural logarithm of \p f over region \p rgn, inverse of
 /// exponential
 ///
-///     \f$\ln(\exp(f)) = f\f$
+/// \f[\ln(\exp(f)) = f\f]
 ///
 /// This loops over the entire domain, including guard/boundary cells by
 /// default (can be changed using the rgn argument)

include/bout/field_accessor.hxx

@@ -1,7 +1,8 @@
+/// \file
+///
 /// FieldAccessor
 ///
 /// Provides quick but unsafe access to field and coordinate system data
-///
 
 #pragma once
 #ifndef FIELD_ACCESSOR_H__
@@ -133,9 +134,9 @@ using Field3DAccessor = FieldAccessor<location, Field3D>;
 ///
 /// Usage:
 ///
-///   ddt(fa)[i] =
+///     ddt(fa)[i] = /* expression */
 ///
-///  where fa is a FieldAccessor, and i is an int
+/// where ``fa`` is a FieldAccessor, and ``i`` is an int
 ///
 template <CELL_LOC location, class FieldType>
 BOUT_HOST_DEVICE inline BoutRealArray& ddt(const FieldAccessor<location, FieldType>& fa) {

include/bout/fv_ops.hxx

@@ -19,71 +19,77 @@
 #include <bout/mesh.hxx>
 
 namespace FV {
-/*!
- * Div ( a Grad_perp(f) ) -- ∇⊥ ( a ⋅ ∇⊥ f) -- Vorticity
- */
-Field3D Div_a_Grad_perp(const Field3D& a, const Field3D& x);
+/// Vorticity:
+/// \f[
+///   \nabla (a \cdot \nabla_\perp(f))
+/// \f]
+Field3D Div_a_Grad_perp(const Field3D& a, const Field3D& f);
 
 [[deprecated("Please use Div_a_Grad_perp instead")]] inline Field3D
 Div_a_Laplace_perp(const Field3D& a, const Field3D& x) {
   return Div_a_Grad_perp(a, x);
 }
 
-/*!
-   * Divergence of a parallel diffusion Div( k * Grad_par(f) )
-   */
+/// Divergence of a parallel diffusion
+/// \f[
+///   \nabla_\parallel(k \cdot \nabla_\parallel(f) )
+/// \f]
 const Field3D Div_par_K_Grad_par(const Field3D& k, const Field3D& f,
                                  bool bndry_flux = true);
 
-/*!
-   * 4th-order derivative in Y, using derivatives
-   * on cell boundaries.
-   *
-   * A one-sided 3rd-order derivative, given a value
-   * at a boundary is:
-   *
-   * d3f/dx3 ~= 16/5 f_b - 6 f_0 + 4 f_1 - 6/5 f_2
-   *
-   * where f_b is the value on the boundary; f_0 is the cell
-   * to the left of the boundary; f_1 to the left of f_0 and f_2
-   * to the left of f_1
-   *
-   *    f_2 | f_1 | f_0 |
-   *                   f_b
-   *
-   * NB: Uses to/from FieldAligned coordinates
-   *
-   * No fluxes through domain boundaries
-   */
+/// 4th-order derivative in Y, using derivatives
+/// on cell boundaries.
+///
+/// A one-sided 3rd-order derivative, given a value
+/// at a boundary is:
+///
+/// \f[
+/// \frac{d^3f}{dx^3} \simeq \tfrac{16}{5} f_b - 6 f_0 + 4 f_1 - \tfrac{6}{5} f_2
+/// \f]
+///
+/// where:
+///
+/// - \f$f_b\f$ is the value on the boundary,
+/// - \f$f_0\f$ is the cell to the left of the boundary,
+/// - \f$f_1\f$ to the left of \f$f_0\f$, and
+/// - \f$f_2\f$ to the left of f_1:
+///
+/// .. code:: text
+///    f_2 | f_1 | f_0 |
+///                   f_b
+///
+/// NB: Uses to/from FieldAligned coordinates
+///
+/// No fluxes through domain boundaries
 const Field3D D4DY4(const Field3D& d, const Field3D& f);
 
-/*!
-   * 4th-order dissipation term
-   *
-   *
-   * A one-sided 3rd-order derivative, given a value
-   * at a boundary is:
-   *
-   * d3f/dx3 ~= 16/5 f_b - 6 f_0 + 4 f_1 - 6/5 f_2
-   *
-   * where f_b is the value on the boundary; f_0 is the cell
-   * to the left of the boundary; f_1 to the left of f_0 and f_2
-   * to the left of f_1
-   *
-   *    f_2 | f_1 | f_0 |
-   *                   f_b
-   */
+/// 4th-order dissipation term
+///
+/// \f[
+/// \frac{d^3f}{dx^3} \simeq \tfrac{16}{5} f_b - 6 f_0 + 4 f_1 - \tfrac{6}{5} f_2
+/// \f]
+///
+/// where:
+///
+/// - \f$f_b\f$ is the value on the boundary,
+/// - \f$f_0\f$ is the cell to the left of the boundary,
+/// - \f$f_1\f$ to the left of \f$f_0\f$, and
+/// - \f$f_2\f$ to the left of f_1:
+///
+/// .. code:: text
+///    f_2 | f_1 | f_0 |
+///                   f_b
 const Field3D D4DY4_Index(const Field3D& f, bool bndry_flux = true);
 
 /*!
    * Stencil used for Finite Volume calculations
    * which includes cell face values L and R
    */
 struct Stencil1D {
-  // Cell centre values
+  /// Cell centre values
   BoutReal c, m, p, mm, pp;
 
-  // Left and right cell face values
+  /// Left and right cell face values
   BoutReal L, R;
 };
 

include/bout/generic_factory.hxx

@@ -1,5 +1,9 @@
+/// \file
 /// Base type for factories
 
+// Copyright 2018-2022 Peter Hill, BOUT++ Team
+// SPDX-License-Identifier: MIT
+
 #pragma once
 #ifndef BOUT_GENERIC_FACTORY_H
 #define BOUT_GENERIC_FACTORY_H
@@ -48,6 +52,14 @@
 ///     RegisterInFactory<Base, Derived, MyFactory, Options*> register("derived_type");
 ///     auto foo = MyFactory::getInstance().create("derived_type");
 ///
+/// In a .cxx file the static members should be declared:
+///
+///     constexpr decltype(MyFactory::type_name) MyFactory::type_name;
+///     constexpr decltype(MyFactory::section_name) MyFactory::section_name;
+///     constexpr decltype(MyFactory::option_name) MyFactory::option_name;
+///     constexpr decltype(MyFactory::default_type) MyFactory::default_type;
+///
+///
 /// @tparam BaseType       The base class that this factory creates
 /// @tparam DerivedFactory The derived factory inheriting from this class
 /// @tparam TypeCreator    The function signature for creating a new BaseType