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

@@ -34,6 +34,7 @@
 #ifndef BOUT_H
 #define BOUT_H
 
+//NOLINTBEGIN(unused-includes)
 #include "bout/build_config.hxx"
 
 #include "bout/boutcomm.hxx"
@@ -53,6 +54,7 @@
 #include "bout/vector3d.hxx"
 #include "bout/version.hxx"
 #include "bout/where.hxx"
+//NOLINTEND(unused-includes)
 
 // BOUT++ main functions
 
@@ -79,6 +81,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

@@ -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

@@ -148,9 +148,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

include/bout/field.hxx

@@ -565,7 +565,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__
@@ -119,9 +120,9 @@ using Field2DAccessor = FieldAccessor<location, Field2D>;
 ///
 /// 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

@@ -13,71 +13,77 @@
 #include <bout/mesh.hxx>
 
 namespace FV {
-/*!
- * Div ( a Grad_perp(f) ) -- ∇⊥ ( a ⋅ ∇⊥ f) -- Vorticity
- */
+/// Vorticity:
+/// \f[
+///   \nabla_\perp (a \cdot \nabla_\perp(f))
+/// \f]
 Field3D Div_a_Grad_perp(const Field3D& a, const Field3D& x);
 
 [[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

include/bout/gyro_average.hxx

@@ -41,7 +41,9 @@ constexpr int GYRO_FLAGS = INVERT_BNDRY_ONE + INVERT_RHS;
 
 /// Gyro-average using Taylor series approximation
 ///
-///     \f$ \Gamma(f) = f + \rho^2 \nabla_\perp^2(f)\f$
+/// \f[
+///    \Gamma(f) = f + \rho^2 \nabla_\perp^2(f)
+/// \f]
 ///
 /// Note: Faster, but less robust than Pade approximations
 ///
@@ -51,7 +53,9 @@ Field3D gyroTaylor0(const Field3D& f, const Field3D& rho);
 
 /// Gyro-average using Pade approximation
 ///
-///     \f$ \Gamma_0 = (1 - \rho^2 \nabla_\perp^2)g = f\f$
+/// \f[
+///    \Gamma_0 = (1 - \rho^2 \nabla_\perp^2)g = f
+/// \f]
 ///
 /// NOTE: Uses Z average of rho for efficient inversion
 ///
@@ -70,7 +74,11 @@ Field3D gyroPade0(const Field3D& f, const Field2D& rho,
 Field3D gyroPade0(const Field3D& f, BoutReal rho, int inner_boundary_flags = GYRO_FLAGS,
                   int outer_boundary_flags = GYRO_FLAGS);
 
-/// Pade approximation \f$Gamma_1 = (1 - \frac{1}{2} \rho^2 \nabla_\perp^2)g = f\f$
+/// Pade approximation
+///
+/// \f[
+///    \Gamma_1 = (1 - \frac{1}{2} \rho^2 \nabla_\perp^2)g = f
+/// \f]
 ///
 /// Note: Have to use Z average of rho for efficient inversion
 ///

include/bout/hyprelib.hxx

@@ -1,24 +1,24 @@
-/*!************************************************************************
+/*! \file ******************************************************************
  * Provides access to the Hypre library, handling initialisation and
  * finalisation.
  *
  * Usage
  * -----
  *
- * #include <bout/hyprelib.hxx>
+ *     #include <bout/hyprelib.hxx>
  *
- * class MyClass {
- *   public:
+ *     class MyClass {
+ *       HypreLib lib;
+ *     public:
+ *       // ...
+ *     };
  *
- *   private:
- *     HypreLib lib;
- * };
  *
- *
- * This will then automatically initialise Hypre the first time an object
- * is created, and finalise it when the last object is destroyed.
- *
- **************************************************************************
+ * This will then automatically ensure Hypre is initialised the first
+ * time an instance is created, and finalise it when the last instances is
+ * destroyed (across all objects using `HypreLib`)
+ */
+/**************************************************************************
  * Copyright 2012 B.D.Dudson, S.Farley, M.V.Umansky, X.Q.Xu
  *
  * Contact: Ben Dudson, [email protected]
@@ -43,16 +43,17 @@
 #ifndef BOUT_HYPRELIB_H
 #define BOUT_HYPRELIB_H
 
-#include "bout/build_config.hxx"
+#include "bout/build_defines.hxx"
 
 namespace bout {
-#if BOUT_HAS_HYPRE
 /*!
  * Handles initialisation and finalisation of Hypre library.
- * The first instance which is created initialises Hypre.
- * Keeps a count of the number of how many instances exist
- * when the last instance is destroyed it finalises Hypre.
+ *
+ * The first instance which is created initialises Hypre. Keeps a
+ * count of the number of how many instances exist, and when the last
+ * instance is destroyed it finalises Hypre.
  */
+#if BOUT_HAS_HYPRE
 class HypreLib {
 public:
   explicit HypreLib();
@@ -64,10 +65,11 @@ public:
 
   ~HypreLib();
 
+  /// Immediately finalise Hypre library
   static void cleanup();
 
 private:
-  static int count; ///< How many instances?
+  static int count; ///< Current number of instances
 };
 
 #else // BOUT_HAS_HYPRE