Merge pull request #2621 from jngrad/doxy-warnings3

Doxygen cleanup

doc/doxygen/Doxyfile

@@ -1472,13 +1472,13 @@ ENABLE_PREPROCESSING   = YES
 # compilation will be performed. Macro expansion can be done in a controlled
 # way by setting EXPAND_ONLY_PREDEF to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
 # then the macro expansion is limited to the macros specified with the
 # PREDEFINED and EXPAND_AS_DEFINED tags.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
 # pointed to by INCLUDE_PATH will be searched when a #include is found.
@@ -1515,7 +1515,8 @@ INCLUDE_FILE_PATTERNS  = *.h *.hpp *.cuh
 # Use the PREDEFINED tag if you want to use a different macro definition that
 # overrules the definition found in the source code.
 
-EXPAND_AS_DEFINED      =
+EXPAND_AS_DEFINED      = NEW_CYLINDRICAL_PROFILE_OBSERVABLE \
+                         NEW_PARAMLESS_OBSERVABLE
 
 # If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then
 # doxygen's preprocessor will remove all references to function-like macros

doc/doxygen/gen_doxyconfig.py

@@ -61,7 +61,7 @@
 
 for feature in sorted(defs.allfeatures):
     configfile.write("  {} \\\n".format(feature))
-configfile.write("  DOXYGEN \\\n".format(feature))
+configfile.write("  DOXYGEN\n".format(feature))
 
 configfile.close()
 print("Done.")

src/core/MpiCallbacks.hpp

@@ -68,10 +68,10 @@ struct callback_concept_t {
 };
 
 /**
- * @brief Concrete implementation of @class callback_concept_t.
+ * @brief Concrete implementation of @ref callback_concept_t.
  *
  * This is an implementation of a callback for a specific callable
- * F and a set of arguments to call it with.
+ * @p F and a set of arguments to call it with.
  */
 template <class F, class... Args>
 struct callback_model_t final : public callback_concept_t {
@@ -129,7 +129,7 @@ auto make_model_impl(CRef &&c, FunctorTypes<C, R, Args...>) {
 }
 
 /**
- * @brief Make a @class callback_model_t for a functor or lambda.
+ * @brief Make a @ref callback_model_t for a functor or lambda.
  *
  * The signature is deduced from F::operator() const, which has
  * to exist and can not be overloaded.
@@ -139,7 +139,7 @@ template <typename F> auto make_model(F &&f) {
 }
 
 /**
- * @brief Make a @class callback_model_t for a function pointer.
+ * @brief Make a @ref callback_model_t for a function pointer.
  *
  * This instantiates a implementation of a callback for a function
  * pointer. The main task here is to transfer the signature from
@@ -319,8 +319,7 @@ class MpiCallbacks {
    * in the MPI loop.
    *
    * @param id The callback to call.
-   * @param par1 First parameter to pass to the callback.
-   * @param par2 Second parameter to pass to the callback.
+   * @param args Arguments for the callback.
    */
   template <class... Args> void call(int id, Args &&... args) const {
     /** Can only be call from master */
@@ -352,7 +351,7 @@ class MpiCallbacks {
    * The method can only be called the master
    * and has the prerequisite that the other nodes are
    * in the MPI loop. Also the function has to be previously
-   * registered e.g. with the @def REGISTER_CALLBACK macro.
+   * registered e.g. with the @ref REGISTER_CALLBACK macro.
    *
    * @param fp Pointer to the function to call.
    * @param args Arguments for the callback.
@@ -446,7 +445,7 @@ using CallbackHandle = MpiCallbacks::CallbackHandle<Args...>;
 /**
  * @brief Helper class to atomatically add callbacks.
  *
- * Should not be used directly, but via @def REGISTER_CALLBACK.
+ * Should not be used directly, but via @ref REGISTER_CALLBACK.
  */
 class RegisterCallback {
 

src/core/communication.hpp

@@ -327,14 +327,4 @@ std::vector<int> mpi_resort_particles(int global_flag);
 
 /*@}*/
 
-/** \name Event codes for \ref mpi_bcast_event
- *  These codes are used by \ref mpi_bcast_event to notify certain changes
- *  of doing something now.
- */
-/*@{*/
-#define P3M_COUNT_CHARGES 0
-#define CHECK_PARTICLES 2
-#define P3M_COUNT_DIPOLES 5
-/*@}*/
-
 #endif

src/core/debug.hpp

@@ -35,8 +35,7 @@
  */
 void check_particle_consistency();
 
-/** check the consistency of the cells and particle_node. Called from
- *  mpi_bcast_event(CHECK_PARTICLES)
+/** check the consistency of the cells and particle_node.
  */
 void check_particles();
 

src/core/event.hpp

@@ -96,8 +96,8 @@ void on_temperature_change();
 
 /** called every time other parameters (timestep,...) are changed. Note that
  *  this does not happen automatically. The callback procedure of the changed
- *  variable is responsible for that by calling \ref mpi_bcast_event (2).
- *  @param parameter is the FIELD_* identifier of the field changed.
+ *  variable is responsible for that.
+ *  @param parameter is the @ref Fields identifier of the field changed.
  */
 void on_parameter_change(int parameter);
 

src/core/utils/tuple.hpp

@@ -2,7 +2,8 @@
 #define ESPRESSO_TUPLE_HPP
 
 /**
- * @file Algorithms for tuple-like inhomogenous containers.
+ * @file
+ * Algorithms for tuple-like inhomogenous containers.
  */
 
 namespace Utils {
@@ -19,8 +20,8 @@ constexpr decltype(auto) apply_impl(F &&f, Tuple &&t,
  *
  * Like std::apply.
  *
- * @tparam F Callable with tuple elements as agruments
- * @tparam Tuple Has to comform to the tuple interface
+ * @tparam F Callable with tuple elements as arguments
+ * @tparam Tuple Has to conform to the tuple interface
  * @param f
  * @param t
  * @return Whatever @p f returns.

src/script_interface/observables/CylindricalProfileObservable.hpp

@@ -91,24 +91,31 @@ class CylindricalProfileObservable : public Observable {
   cylindrical_profile_observable() const = 0;
 };
 
-#define NEW_CYLINDRICAL_PROFILE_OBSERVABLE(obs_name)                           \
-  class obs_name : public CylindricalProfileObservable {                       \
-  public:                                                                      \
-    obs_name() : m_observable(new ::Observables::obs_name()){};                \
-                                                                               \
-    std::shared_ptr<::Observables::Observable> observable() const override {   \
-      return m_observable;                                                     \
-    }                                                                          \
-                                                                               \
-    std::shared_ptr<::Observables::CylindricalProfileObservable>               \
-    cylindrical_profile_observable() const override {                          \
-      return m_observable;                                                     \
-    }                                                                          \
-                                                                               \
-  private:                                                                     \
-    std::shared_ptr<::Observables::obs_name> m_observable;                     \
-  };
+/** Cython interface for cylindrical profile observables.
+ *  Create new interfaces with @ref NEW_CYLINDRICAL_PROFILE_OBSERVABLE.
+ *  @tparam CoreObs The core class exposed in Cython by this class.
+ */
+template <class CoreObs>
+class CylindricalProfileObservableInterface
+    : public CylindricalProfileObservable {
+public:
+  CylindricalProfileObservableInterface() : m_observable(new T()) {}
+
+  std::shared_ptr<::Observables::Observable> observable() const override {
+    return m_observable;
+  }
+
+  std::shared_ptr<::Observables::CylindricalProfileObservable>
+  cylindrical_profile_observable() const override {
+    return m_observable;
+  }
+
+private:
+  std::shared_ptr<CoreObs> m_observable;
+};
 
+#define NEW_CYLINDRICAL_PROFILE_OBSERVABLE(name)                               \
+  using name = CylindricalProfileObservableInterface<::Observables::name>;
 NEW_CYLINDRICAL_PROFILE_OBSERVABLE(CylindricalDensityProfile)
 NEW_CYLINDRICAL_PROFILE_OBSERVABLE(CylindricalVelocityProfile)
 NEW_CYLINDRICAL_PROFILE_OBSERVABLE(CylindricalFluxDensityProfile)

src/script_interface/observables/ParamlessObservable.hpp

@@ -33,19 +33,25 @@
 namespace ScriptInterface {
 namespace Observables {
 
-#define NEW_PARAMLESS_OBSERVABLE(obs_name)                                     \
-  class obs_name : public Observable {                                         \
-  public:                                                                      \
-    obs_name() : m_observable(new ::Observables::obs_name()){};                \
-                                                                               \
-    std::shared_ptr<::Observables::Observable> observable() const override {   \
-      return m_observable;                                                     \
-    };                                                                         \
-                                                                               \
-  private:                                                                     \
-    std::shared_ptr<::Observables::obs_name> m_observable;                     \
-  };
-
+/** Cython interface for parameter-free observables.
+ *  Create new observables with @ref NEW_PARAMLESS_OBSERVABLE.
+ *  @tparam CoreObs The core class exposed in Cython by this class.
+ */
+template <class CoreObs>
+class ParamlessObservableInterface : public Observable {
+public:
+  ParamlessObservableInterface() : m_observable(new CoreObs()) {}
+
+  std::shared_ptr<::Observables::Observable> observable() const override {
+    return m_observable;
+  }
+
+private:
+  std::shared_ptr<CoreObs> m_observable;
+};
+
+#define NEW_PARAMLESS_OBSERVABLE(name)                                         \
+  using name = ParamlessObservableInterface<::Observables::name>;
 NEW_PARAMLESS_OBSERVABLE(StressTensor)
 
 } /* namespace Observables */