Cleanup Doxygen documentation

Fix outdated instructions in chapter on bonded interactions.
Remove automatic linking of words that collide with class names
and namespaces due to the large number of false positives.

doc/doxygen/Doxyfile.in

@@ -319,7 +319,7 @@ TOC_INCLUDE_HEADINGS   = 5
 # globally by setting AUTOLINK_SUPPORT to NO.
 # The default value is: YES.
 
-AUTOLINK_SUPPORT       = YES
+AUTOLINK_SUPPORT       = NO
 
 # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
 # to include (a tag file for) the STL sources as input, then you should set this

src/core/TabulatedPotential.hpp

@@ -38,7 +38,7 @@ struct TabulatedPotential {
   double minval = -1.0;
   /** Position on the x-axis of the last tabulated value. */
   double maxval = -1.0;
-  /** %Distance on the x-axis between tabulated values. */
+  /** Distance on the x-axis between tabulated values. */
   double invstepsize = 0.0;
   /** Tabulated forces. */
   std::vector<double> force_tab;

src/core/bonded_interactions/bonded_coulomb.hpp

@@ -33,9 +33,9 @@
 
 #include <cmath>
 
-/** Parameters for %Coulomb bond Potential */
+/** Parameters for Coulomb bond Potential */
 struct BondedCoulomb {
-  /** %Coulomb prefactor */
+  /** Coulomb prefactor */
   double prefactor;
 
   double cutoff() const { return 0.; }
@@ -58,7 +58,7 @@ struct BondedCoulomb {
 
 /** Compute the bonded Coulomb pair force.
  *  @param[in]  q1q2      Product of the particle charges.
- *  @param[in]  dx        %Distance between the particles.
+ *  @param[in]  dx        Distance between the particles.
  */
 inline boost::optional<Utils::Vector3d>
 BondedCoulomb::force(double const q1q2, Utils::Vector3d const &dx) const {
@@ -74,7 +74,7 @@ BondedCoulomb::force(double const q1q2, Utils::Vector3d const &dx) const {
 
 /** Compute the bonded Coulomb pair energy.
  *  @param[in]  q1q2      Product of the particle charges.
- *  @param[in]  dx        %Distance between the particles.
+ *  @param[in]  dx        Distance between the particles.
  */
 inline boost::optional<double>
 BondedCoulomb::energy(double const q1q2, Utils::Vector3d const &dx) const {

src/core/bonded_interactions/bonded_coulomb_sr.hpp

@@ -37,7 +37,7 @@
 #include <cmath>
 #include <functional>
 
-/** Parameters for %Coulomb bond short-range Potential */
+/** Parameters for Coulomb bond short-range Potential */
 struct BondedCoulombSR {
   /** charge factor */
   double q1q2;
@@ -67,8 +67,8 @@ struct BondedCoulombSR {
 };
 
 /** Compute the short-range bonded Coulomb pair force.
- *  @param[in]  dx        %Distance between the particles.
- *  @param[in]  kernel    %Coulomb force kernel.
+ *  @param[in]  dx        Distance between the particles.
+ *  @param[in]  kernel    Coulomb force kernel.
  */
 inline boost::optional<Utils::Vector3d> BondedCoulombSR::force(
     Utils::Vector3d const &dx,
@@ -84,8 +84,8 @@ inline boost::optional<Utils::Vector3d> BondedCoulombSR::force(
 /** Compute the short-range bonded Coulomb pair energy.
  *  @param[in]  p1        First particle.
  *  @param[in]  p2        Second particle.
- *  @param[in]  dx        %Distance between the particles.
- *  @param[in]  kernel    %Coulomb energy kernel.
+ *  @param[in]  dx        Distance between the particles.
+ *  @param[in]  kernel    Coulomb energy kernel.
  */
 inline boost::optional<double> BondedCoulombSR::energy(
     Particle const &p1, Particle const &p2, Utils::Vector3d const &dx,

src/core/bonded_interactions/bonded_interactions.dox

@@ -34,21 +34,21 @@
  *      calculation functions.
  *    - Register the new bond type.
  *  * ScriptInterface:
- *    - Define the %ScriptInterface class of the new bond type, which serves as
+ *    - Define the @c ScriptInterface class of the new bond type, which serves as
  *      the connection between the C++ core and the Python representation of the
  *      bond.
  *  * Python interface:
  *    - Import the definition of the interaction struct from the core
  *    - Implement a class for the bonded interaction derived from the Python
- *      \c BondedInteraction base class
+ *      @c BondedInteraction base class
  *
  *  @subsection bondedIA_new_struct Defining the new interaction
  *
  *  Every interaction resides in its own source .cpp and .hpp files. A simple
  *  example for a bonded interaction is the FENE bond in @ref fene.hpp and
  *  @ref fene.cpp. Use these two files as templates for your interaction.
  *
- *  The first step is to create a new \c struct which represents your new
+ *  The first step is to create a new @c struct which represents your new
  *  bond type inside the .hpp file. It needs to have the following members:
  *
  *  * @code{.cpp}
@@ -59,7 +59,7 @@
  *  * @code{.cpp}
  *    double cutoff() const { return r0 + drmax; }
  *    @endcode
- *    The return value of \c cutoff() should be as large as the interaction
+ *    The return value of @c cutoff() should be as large as the interaction
  *    range of the new interaction. This is only relevant to pairwise bonds.
  *    In all other cases, the return value should be 0, namely angle bonds,
  *    dihedral bonds as well as other bonds that don't have an interaction
@@ -70,9 +70,9 @@
  *    boost::optional<Utils::Vector3d> force(Utils::Vector3d const &dx) const;
  *    @endcode
  *    This function returns the bond force. If it is a bond involving three
- *    or four particles, a \c std::tuple with three or four force vectors
+ *    or four particles, a @c std::tuple with three or four force vectors
  *    has to be returned, respectively.
- *    - The returned value is in a \c boost::optional container if the bond is
+ *    - The returned value is in a @c boost::optional container if the bond is
  *      breakable. If the bond is broken, the returned object is empty; this
  *      will stop the integrator with a runtime error.
  *    - The function can make use of a pre-calculated distance vector (\p dx)
@@ -95,7 +95,7 @@
  *    @endcode
  *    All values the bond needs to function properly should be passed as
  *    arguments to this constructor.
- *  * A template function for serialization called \c serialize. This is for
+ *  * A template function for serialization called @c serialize. This is for
  *    communication between nodes in parallel computations.
  *    The following function can serve as a starting point.
  *    @code{.cpp}
@@ -142,7 +142,7 @@
  *      of the functions @ref calc_bond_pair_force(), @ref
  *      calc_bonded_three_body_force() or @ref calc_bonded_four_body_force(),
  *      depending on how many bond partners there are.
- *    - Add the new entry to the \c if - \c else chain, like in the following
+ *    - Add the new entry to the @c if - @c else chain, like in the following
  *      example
  *      @code{.cpp}
  *      // ...
@@ -153,9 +153,9 @@
  *      @endcode
  *  * In energy_inline.hpp:
  *    - A call to the new bond's force calculation needs to be placed in @ref
- *      calc_bonded_energy. Find the \c if - \c else chain that corresponds
+ *      calc_bonded_energy. Find the @c if - @c else chain that corresponds
  *      to the correct number of bond partners.
- *    - Add the new entry to the \c if - \c else chain, like in the following
+ *    - Add the new entry to the @c if - @c else chain, like in the following
  *      example
  *      @code{.cpp}
  *      // ...
@@ -177,53 +177,47 @@
  *  @subsection bondedIA_new_script_interface Registering the new interaction in the ScriptInterface
  *
  *  * In src/script_interface/interactions/BondedInteraction.hpp:
- *    Add a new class representing your new bond type in the %ScriptInterface.
+ *    Add a new class representing your new bond type in the @c ScriptInterface.
  *    - We recommend that the new class has the same name as the interaction in the core.
- *    - You can use ScriptInterface::Interactions::FeneBond as a template.
- *    - The class must be derived from ScriptInterface::Interactions::BondedInteraction.
+ *    - You can use @ref ScriptInterface::Interactions::FeneBond as a template.
+ *    - The class must be derived from @ref ScriptInterface::Interactions::BondedInteraction.
  *    - It is recommended to include the statement
  *      @code{.cpp}
  *      using CoreBondedInteraction = ::YourNewBond;
  *      @endcode
- *      where \c YourNewBond is the core type you defined.
+ *      where @c YourNewBond is the core type you defined.
  *    - Implement a member function with the signature
  *      @code{.cpp}
  *      void construct_bond(VariantMap const &params) override { /* ... */ }
  *      @endcode
- *      In this function, the member \c m_bonded_ia shall be initialized using
- *      the parameters that are given in <tt>params</tt>. Use the constructor
- *      of \c %FeneBond as a template. An instance of your core type
- *      \c %YourNewBond should be initialized, which is then used to initialize
- *      a \c std::shared_ptr to a \ref Bonded_IA_Parameters, which is then
- *      assigned to \c m_bonded_ia.
- *      The values of the parameters are extracted from \c params using
+ *      In this function, the member @c m_bonded_ia shall be initialized using
+ *      the parameters that are given in @c params. Use the @c construct_bond()
+ *      method of @c FeneBond as a template.
+ *      An instance of the core type @c YourNewBond should be initialized,
+ *      which is then used to initialize
+ *      a @c std::shared_ptr to a @ref Bonded_IA_Parameters, which is then
+ *      assigned to @c m_bonded_ia.
+ *      The values of the parameters are extracted from @c params using
  *      @code{.cpp}
  *      get_value<parameter_type>(params, "parameter_name")
  *      @endcode
- *      where \c parameter_type is the type of the parameter, e.g. \c double or
- *      \c int or even \c std::string, and <tt>"parameter_name"</tt> must be
+ *      where @c parameter_type is the type of the parameter, e.g. @c double or
+ *      @c int or even @c std::string, and <tt>"parameter_name"</tt> must be
  *      replaced by the name of the respective parameter. This name must be the
  *      same as in the Python interface, but may differ from the name in the
  *      core interaction type. It is, however, recommended to use the same
  *      names for both the Python interface and the ESPResSo core for
  *      consistency whenever possible.
- *    - Implement a member function called <tt>get_struct()</tt>, which returns
- *      the bond parameters, which are stored in <tt>m_bonded_ia</tt>.
- *      The return type should be a reference to an object of the new type
- *      <tt>YourNewBond</tt> that you defined in the core. If you included the
- *      above <tt>using</tt> statement, you can simply copy the routine from
- *      \c %FeneBond, since <tt>CoreBondedInteraction</tt> is already set to
- *      the correct core type.
- *    - Implement the constructor. We recommend to adapt it from \c %FeneBond.
+ *    - Implement the constructor. We recommend to adapt it from @c FeneBond.
  *      All it needs to do is to register its parameters so they can be set
  *      from Python. For this purpose, call
  *      @code{.cpp}
  *      add_parameters(/* ... */);
  *      @endcode
- *      inside the constructors. It expects a vector of
- *      \ref ScriptInterface::AutoParameter. Usually, this vector is initialized
+ *      inside the constructor. It expects a vector of
+ *      @ref ScriptInterface::AutoParameter. Usually, this vector is initialized
  *      using an initializer list, each element of which is in itself a list which
- *      initializes one instance of \c AutoParameter (see @ref AutoParameter.hpp).
+ *      initializes one instance of @c AutoParameter (see @ref AutoParameter.hpp).
  *      One of many ways to initialize these parameters is to pass the parameter name
  *      as a string, a custom setter and a custom getter function. The parameters
  *      are typically made read-only by passing <tt>AutoParameter::read_only</tt>
@@ -232,21 +226,21 @@
  *
  *  * In src/script_interface/interactions/initialize.cpp:
  *    Your new interaction type needs to be registered here so that the
- *    %ScriptInterface can find it by its name. In the function \c initialize
+ *    @c ScriptInterface can find it by its name. In the function @c initialize
  *    add a new line of the form
  *    @code{.cpp}
  *    om->register_new<YourNewBond>("Interactions::YourNewBond");
  *    @endcode
- *    where \c YourNewBond must be replaced by the name of your new bond type.
- *    The string is used to match the %ScriptInterface class with the Python
+ *    where @c YourNewBond must be replaced by the name of your new bond type.
+ *    The string is used to match the @c ScriptInterface class with the Python
  *    class (see below).
  *
  *
  *
  *  @subsection bondedIA_new_interface Adding the interaction in the Python interface
  *
  *  * In file <tt>src/python/espressomd/interactions.py</tt>:
- *    - Add the bonded interaction to \c BONDED_IA.
+ *    - Add the bonded interaction to @c BONDED_IA.
  *      The order of the enum values must match the order of types in
  *      @ref Bonded_IA_Parameters exactly:
  *      @code{.py}
@@ -263,9 +257,9 @@
  *      _so_name = "Interactions::YourNewBond"
  *      _type_number = BONDED_IA.YOURNEWBOND
  *      @endcode
- *      where you put the name of your bond instead of \c YourNewBond.
- *      This connects the %ScriptInterface class with the Python class.
- *      The type number is the new enum value from \c BONDED_IA.
+ *      where you put the name of your bond instead of @c YourNewBond.
+ *      This connects the @c ScriptInterface class with the Python class.
+ *      The type number is the new enum value from @c BONDED_IA.
  *  * In file <tt>testsuite/python/interactions_bonded_interface.py</tt>:
  *    - Add a test case to verify that parameters set and gotten from the
  *      interaction are consistent.

src/core/bonded_interactions/bonded_tab.hpp

@@ -120,7 +120,7 @@ struct TabulatedDihedralBond : public TabulatedBond {
  *  particles. For distances smaller than the tabulated range it uses a linear
  *  extrapolation based on the first two tabulated force values.
  *
- *  @param[in]  dx        %Distance between the particles.
+ *  @param[in]  dx        Distance between the particles.
  */
 inline boost::optional<Utils::Vector3d>
 TabulatedDistanceBond::force(Utils::Vector3d const &dx) const {
@@ -139,7 +139,7 @@ TabulatedDistanceBond::force(Utils::Vector3d const &dx) const {
  *  extrapolation based on the first two tabulated force values and the first
  *  tabulated energy value.
  *
- *  @param[in]  dx        %Distance between the particles.
+ *  @param[in]  dx        Distance between the particles.
  */
 inline boost::optional<double>
 TabulatedDistanceBond::energy(Utils::Vector3d const &dx) const {

src/core/bonded_interactions/fene.hpp

@@ -70,7 +70,7 @@ struct FeneBond {
 };
 
 /** Compute the FENE bond force.
- *  @param[in]  dx        %Distance between the particles.
+ *  @param[in]  dx        Distance between the particles.
  */
 inline boost::optional<Utils::Vector3d>
 FeneBond::force(Utils::Vector3d const &dx) const {
@@ -95,7 +95,7 @@ FeneBond::force(Utils::Vector3d const &dx) const {
 }
 
 /** Compute the FENE bond energy.
- *  @param[in]  dx        %Distance between the particles.
+ *  @param[in]  dx        Distance between the particles.
  */
 inline boost::optional<double>
 FeneBond::energy(Utils::Vector3d const &dx) const {

src/core/bonded_interactions/harmonic.hpp

@@ -65,7 +65,7 @@ struct HarmonicBond {
 };
 
 /** Compute the harmonic bond force.
- *  @param[in]  dx        %Distance between the particles.
+ *  @param[in]  dx        Distance between the particles.
  */
 inline boost::optional<Utils::Vector3d>
 HarmonicBond::force(Utils::Vector3d const &dx) const {
@@ -89,7 +89,7 @@ HarmonicBond::force(Utils::Vector3d const &dx) const {
 }
 
 /** Compute the harmonic bond energy.
- *  @param[in]  dx        %Distance between the particles.
+ *  @param[in]  dx        Distance between the particles.
  */
 inline boost::optional<double>
 HarmonicBond::energy(Utils::Vector3d const &dx) const {

src/core/bonded_interactions/quartic.hpp

@@ -63,7 +63,7 @@ struct QuarticBond {
 };
 
 /** Compute the quartic bond force.
- *  @param[in]  dx        %Distance between the particles.
+ *  @param[in]  dx        Distance between the particles.
  */
 inline boost::optional<Utils::Vector3d>
 QuarticBond::force(Utils::Vector3d const &dx) const {
@@ -88,7 +88,7 @@ QuarticBond::force(Utils::Vector3d const &dx) const {
 }
 
 /** Compute the quartic bond energy.
- *  @param[in]  dx        %Distance between the particles.
+ *  @param[in]  dx        Distance between the particles.
  */
 inline boost::optional<double>
 QuarticBond::energy(Utils::Vector3d const &dx) const {

src/core/bonded_interactions/thermalized_bond_kernel.hpp

@@ -38,7 +38,7 @@
 /** Separately thermalizes the com and distance of a particle pair.
  *  @param[in]  p1        First particle.
  *  @param[in]  p2        Second particle.
- *  @param[in]  dx        %Distance between the particles.
+ *  @param[in]  dx        Distance between the particles.
  *  @return the forces on @p p1 and @p p2
  */
 inline boost::optional<std::tuple<Utils::Vector3d, Utils::Vector3d>>

src/core/electrostatics/mmm1d.hpp

@@ -21,7 +21,7 @@
 
 /**
  * @file
- * MMM1D algorithm for long-range %Coulomb interactions on the CPU.
+ * MMM1D algorithm for long-range Coulomb interactions on the CPU.
  * Implementation of the MMM1D method for the calculation of the electrostatic
  * interaction in one-dimensionally periodic systems. For details on the
  * method see MMM in general. The MMM1D method works only with the N-squared

src/core/electrostatics/mmm1d_gpu.hpp

@@ -21,7 +21,7 @@
 
 /**
  * @file
- * MMM1D algorithm for long-range %Coulomb interactions on the GPU.
+ * MMM1D algorithm for long-range Coulomb interactions on the GPU.
  * Implementation of the MMM1D method for the calculation of the electrostatic
  * interaction in one-dimensionally periodic systems. For details on the
  * method see MMM in general. The MMM1D method works only with the N-squared

src/core/electrostatics/p3m.hpp

@@ -172,8 +172,8 @@ struct CoulombP3M : public Coulomb::Actor<CoulombP3M> {
   /**
    * @brief Assign a single charge into the current charge grid.
    *
-   * @param[in] q          %Particle charge
-   * @param[in] real_pos   %Particle position in real space
+   * @param[in] q          Particle charge
+   * @param[in] real_pos   Particle position in real space
    * @param[out] inter_weights Cached interpolation weights to be used.
    */
   void assign_charge(double q, Utils::Vector3d const &real_pos,

src/core/energy_inline.hpp

@@ -68,7 +68,7 @@
  *  @param ia_params  the interaction parameters between the two particles
  *  @param d          vector between p1 and p2.
  *  @param dist       distance between p1 and p2.
- *  @param coulomb_kernel   %Coulomb energy kernel.
+ *  @param coulomb_kernel   Coulomb energy kernel.
  *  @return the short-range interaction energy between the two particles
  */
 inline double calc_non_bonded_pair_energy(
@@ -168,7 +168,7 @@ inline double calc_non_bonded_pair_energy(
  *  @param dist      distance between p1 and p2.
  *  @param dist2     distance squared between p1 and p2.
  *  @param[in] ia_params        non-bonded interaction kernels.
- *  @param[in] coulomb_kernel   %Coulomb energy kernel.
+ *  @param[in] coulomb_kernel   Coulomb energy kernel.
  *  @param[in] dipoles_kernel   Dipolar energy kernel.
  *  @param[in,out] obs_energy   energy observable.
  */