docu: examples: improve examples

Author: torbjoernk

README.md

@@ -33,7 +33,7 @@ Doxygen generated documentation can be found [on the PinT server][documentation]
 Currently, it features the following content:
 
 * \subpage #page_building_installing
-* \subpage #page_examples
+* \ref Examples
 * \subpage #page_contributing
 * \subpage #page_style_guide
 * \subpage #page_troubleshooting

doc/source/examples.md

@@ -138,7 +138,7 @@ latest release from [GitHub][github_releases].
 ## Building with vanilla make
 
 A sample `Makefile` is included in the `advection_diffusion` example.  This may be of particular
-interested to advanced users wishing to incorporate \rm PFASST++ into their existing code bases.
+interested to advanced users wishing to incorporate \em PFASST++ into their existing code bases.
 
 
 [Boost]: https://boost.org/

doc/source/installing.md

@@ -61,7 +61,7 @@ using double quotes.
 
 ### Define Guards
 
-Use `#define` guards in header files to prevent multiple inclusion.
+Use `#%define` guards in header files to prevent multiple inclusion.
 The variable defined should be derived from the header file name
 itself.  For example, a header file `my_header.hpp` in the folder
 `PFASST/include/subfolder` should have the following define guard:

doc/source/style_guide.md

@@ -1,9 +1,12 @@
-/*
- * Advection/diffusion sweeper.
+/**
+ * @defgroup AdvectionDiffusionFiles Files
+ * @ingroup AdvectionDiffusion
+ *
+ * @file examples/advection_diffusion/advection_diffusion_sweeper.hpp
+ * @since v0.1.0
  */
-
-#ifndef _ADVECTION_DIFFUSION_SWEEPER_HPP_
-#define _ADVECTION_DIFFUSION_SWEEPER_HPP_
+#ifndef _EXAMPLES__ADVEC_DIFF__ADVECTION_DIFFUSION_SWEEPER_HPP_
+#define _EXAMPLES__ADVEC_DIFF__ADVECTION_DIFFUSION_SWEEPER_HPP_
 
 #include <cassert>
 #include <complex>
@@ -32,17 +35,45 @@ namespace pfasst
 {
   namespace examples
   {
+    /**
+     * Advection-Diffusion example
+     *
+     * @defgroup AdvectionDiffusion Advection Diffusion
+     * @ingroup Examples
+     *
+     * This directory contains several implementations of an advection/diffusion solver using the
+     * PFASST framework.
+     *
+     * All of the solvers use the SDC sweeper defined in `advection_diffusion_sweeper.hpp`, and the FFT
+     * routines in `fft.hpp`.
+     *
+     * The implementations are, in order of complexity:
+     *
+     *  - `vanilla_sdc.cpp` - basic example that uses an encapsulated IMEX sweeper.
+     *
+     *  - `serial_mlsdc.cpp` - basic multi-level version that uses polynomial interpolation in time and
+     *    spectral interpolation in space, as defined in `specrtal_transfer_1d.hpp`.
+     *
+     *  - `serial_mlsdc_autobuild.cpp` - same as above, but uses the "auto build" feature to shorten
+     *    `main`.
+     */
     namespace advection_diffusion
     {
       /**
-       * Containers for errors/residuals etc.
+       * @name Containers for errors/residuals etc.
+       * @{
        */
       typedef map<tuple<size_t, size_t>, double> error_map; // step, iteration -> error
       typedef map<size_t, error_map> residual_map; // level, (step, iteration) -> residual
+      //! @}
 
       typedef error_map::value_type vtype;
       typedef error_map::key_type ktype;
 
+      /**
+       * advection-diffusion sweeper with semi-implicit time-integration.
+       * @ingroup AdvectionDiffusion
+       */
       template<typename time = pfasst::time_precision>
       class AdvectionDiffusionSweeper
         : public encap::IMEXSweeper<time>
@@ -271,4 +302,4 @@ namespace pfasst
   }  // ::pfasst::examples
 }  // ::pfasst
 
-#endif
+#endif  // _EXAMPLES__ADVEC_DIFF__ADVECTION_DIFFUSION_SWEEPER_HPP_

examples/advection_diffusion/README.md

@@ -1,11 +1,10 @@
-/*
- * FFT helper class.
- *
- * Please note: side affects galore!  This is not my best work...
+/**
+ * @ingroup AdvectionDiffusionFiles
+ * @file examples/advection_diffusion/fft.hpp
+ * @since v0.1.0
  */
-
-#ifndef _FFT_HPP_
-#define _FFT_HPP_
+#ifndef _EXAMPLES__ADVEC_DIFF__FFT_HPP_
+#define _EXAMPLES__ADVEC_DIFF__FFT_HPP_
 
 #include <map>
 #include <memory>
@@ -23,6 +22,13 @@ namespace pfasst
   {
     namespace advection_diffusion
     {
+      /**
+       * FFT helper class.
+       *
+       * @warning Side affects galore! This is not my best work ...
+       *
+       * @ingroup AdvectionDiffusion
+       */
       class FFT
       {
           struct workspace {
@@ -83,4 +89,4 @@ namespace pfasst
   }  // ::pfasst::examples
 }  // ::pfasst
 
-#endif
+#endif  // _EXAMPLES__ADVEC_DIFF__FFT_HPP_

examples/advection_diffusion/advection_diffusion_sweeper.hpp

@@ -1,7 +1,9 @@
-/*
- * Advection/diffusion example using an encapsulated IMEX sweeper.
+/**
+ * Advection-Diffusion with MPI-enabled PFASST.
  *
- * This example uses MPI PFASST.
+ * @ingroup AdvectionDiffusionFiles
+ * @file examples/advection_diffusion/mpi_pfasst.cpp
+ * @since v0.2.0
  */
 
 #include <cassert>
@@ -31,6 +33,13 @@ namespace pfasst
   {
     namespace advection_diffusion
     {
+      /**
+       * Advection/diffusion example using an encapsulated IMEX sweeper.
+       *
+       * This example uses MPI PFASST.
+       *
+       * @ingroup AdvectionDiffusion
+       */
       error_map run_mpi_pfasst(double abs_residual_tol, size_t niters=4)
       {
         const size_t nsteps = 4;

examples/advection_diffusion/fft.hpp

@@ -1,9 +1,10 @@
-/*
- * Advection/diffusion example using an encapsulated IMEX sweeper.
+/**
+ * Advection-Diffusion with serial MLSDC.
  *
- * This example uses a (serial) multi-level SDC sweeper.
+ * @ingroup AdvectionDiffusionFiles
+ * @file examples/advection_diffusion/serial_mlsdc.cpp
+ * @since v0.1.0
  */
-
 #include <memory>
 using namespace std;
 
@@ -26,6 +27,13 @@ namespace pfasst
   {
     namespace advection_diffusion
     {
+      /**
+       * Advection/diffusion example using an encapsulated IMEX sweeper.
+       *
+       * This example uses a (serial) multi-level SDC sweeper.
+       *
+       * @ingroup AdvectionDiffusion
+       */
       tuple<error_map, residual_map> run_serial_mlsdc(size_t nlevs)
       {
         MLSDC<> mlsdc;

examples/advection_diffusion/mpi_pfasst.cpp

@@ -1,12 +1,10 @@
-/*
- * Advection/diffusion example using an encapsulated IMEX sweeper.
+/**
+ * Advection-Diffusion MLSDC with _auto builder_.
  *
- * This example uses a (serial) multi-level SDC sweeper.  It is
- * functionally exactly the same as ex2.cpp, but uses the 'auto
- * builder' to shorten the build and setup stages of the MLSDC
- * controller.
+ * @ingroup AdvectionDiffusionFiles
+ * @file examples/advection_diffusion/serial_mlsdc_autobuild.cpp
+ * @since v0.1.0
  */
-
 #include <cassert>
 #include <cstdlib>
 #include <memory>
@@ -37,6 +35,15 @@ namespace pfasst
   {
     namespace advection_diffusion
     {
+      /**
+       * Advection/diffusion example using an encapsulated IMEX sweeper.
+       *
+       * This example uses a (serial) multi-level SDC sweeper.
+       * It is functionally exactly the same as serial_mlsdc.cpp, but uses the _auto builder_ to
+       * shorten the build and setup stages of the MLSDC controller.
+       *
+       * @ingroup AdvectionDiffusion
+       */
       tuple<error_map, residual_map> run_serial_mlsdc_autobuild()
       {
         MLSDC<> mlsdc;