Fix random doxygen warnings and typos
authorAndrey Alekseenko <al42and@gmail.com>
Fri, 16 Oct 2020 14:16:04 +0000 (16:16 +0200)
committerAndrey Alekseenko <al42and@gmail.com>
Mon, 19 Oct 2020 12:12:23 +0000 (12:12 +0000)
Silence annoying
"/builds/gromacs/gromacs/src/gromacs/math/vectypes.h:87: error:
gmx::BasicVector: is in library file(s), but appears in public
documentation" from source-check pipeline (appears to be false-positive
due to a forward-declaration in a random file). I was not able to come
up with a quick fix for the underlying problem in check-source, and,
from my understanding, there are plans for refactoring it soon anyway;
so I went with a suppression here.

Fix a bunch of random typos throughout the code.

Fix some unbalanced Doxygen's \{ and \}. And one widowed @}.

Fix some \copydocs (not all).

Remove a nasty non-breakable-space that was messing up block
indentation in Sphinx docs.

28 files changed:
docs/doxygen/suppressions.txt
docs/reference-manual/algorithms/free-energy-calculations.rst
src/gromacs/analysisdata/modules/average.h
src/gromacs/applied_forces/densityfitting/densityfittingforceprovider.cpp
src/gromacs/ewald/pme_gather.cu
src/gromacs/ewald/pme_gpu_internal.cpp
src/gromacs/fileio/warninp.h
src/gromacs/gpu_utils/devicebuffer.cuh
src/gromacs/gpu_utils/devicebuffer_ocl.h
src/gromacs/listed_forces/bonded.cpp
src/gromacs/math/densityfittingforce.cpp
src/gromacs/math/paddedvector.h
src/gromacs/math/vec.h
src/gromacs/mdlib/leapfrog_gpu.cu
src/gromacs/mdlib/update_constrain_gpu_impl.cu
src/gromacs/nbnxm/nbnxm_geometry.h
src/gromacs/nbnxm/nbnxm_gpu.h
src/gromacs/nbnxm/nbnxm_gpu_data_mgmt.cpp
src/gromacs/nbnxm/opencl/nbnxm_ocl_types.h
src/gromacs/restraint/restraintmdmodule.h
src/gromacs/simd/impl_reference/impl_reference_simd_double.h
src/gromacs/simd/impl_reference/impl_reference_simd_float.h
src/gromacs/simd/impl_reference/impl_reference_util_double.h
src/gromacs/simd/impl_reference/impl_reference_util_float.h
src/gromacs/simd/simd.h
src/gromacs/simd/simd_math.h
src/gromacs/simd/tests/simd_math.cpp
src/gromacs/utility/arrayref.h

index 6a976c4971d17e308bdc4b0ed62a0ba137829ec0..a6538a629f163f194e75486586a409382fbb6cd7 100644 (file)
@@ -37,6 +37,9 @@ src/gromacs/nbnxm/kernels_simd_4xm/kernel_common.h: warning: should include "nbn
 # This seems to be a false positive
 src/gromacs/nbnxm/cuda/nbnxm_cuda_types.h: error: NbnxmGpu: is in internal file(s), but appears in public documentation
 
+# False positive caused by forward-declaration of BasicVector in src/testutils/refdata.h
+src/gromacs/math/vectypes.h: error: gmx::BasicVector: is in library file(s), but appears in public documentation
+
 # Temporary while we change the SIMD implementation
 src/gromacs/simd/impl_sparc64_hpc_ace/impl_sparc64_hpc_ace_common.h: warning: should include "simd.h"
 
index 383fbef0971f824a30a7c5a6e492081db403dd1f..77cd81d7c6dfa7363e5b7d7323eed3b241cc52d3 100644 (file)
@@ -36,7 +36,7 @@ the right-hand term.
 .. figure:: plots/free2.*
             :width: 6.00000cm
 
-            Free energy cycles. **B:** to calculate
+            Free energy cycles. **B:** to calculate
             :math:`\Delta G_{12}`, the free energy difference for binding of
             inhibitors **I** respectively **I**\ :math:`^{\prime}` to enzyme
             **E**.
index 52527ccb7d5f9b6e3283314e521a3aa31e448ae6..01e62d61e17a702b7fa2bd04855e194567bcaba1 100644 (file)
@@ -65,7 +65,7 @@ namespace gmx
  *
  * Output data contains a column for each data set in the input data, and a
  * frame for each column in the input data.  If different data sets have
- * different number of columns, the frame count accomodates the largest data
+ * different number of columns, the frame count accommodates the largest data
  * set.  Other columns are padded with zero values that are additionally marked
  * as missing.
  * Each value in the output data is the average of the corresponding
index c0dab954369b5faa312a254d21b821e5588a7e9e..c2442bbd385e01be8f3b46b27b7ff99ea6501f66 100644 (file)
@@ -146,7 +146,7 @@ void DensityFittingForceProviderState::broadcastState(MPI_Comm communicator, boo
 class DensityFittingForceProvider::Impl
 {
 public:
-    //! \copydoc DensityFittingForceProvider(const DensityFittingParameters &parameters)
+    //! \copydoc DensityFittingForceProvider::DensityFittingForceProvider
     Impl(const DensityFittingParameters&             parameters,
          basic_mdspan<const float, dynamicExtents3D> referenceDensity,
          const TranslateAndScale&                    transformationToDensityLattice,
index 52814c4ce44f372c70c1be0366c88e609779966f..160f544d3ecb3ace27be9eba5a7265f5a5845697 100644 (file)
@@ -438,7 +438,7 @@ __launch_bounds__(c_gatherMaxThreadsPerBlock, c_gatherMinBlocksPerMP) __global__
     else
     {
         const float3* __restrict__ gm_coordinates = asFloat3(kernelParams.atoms.d_coordinates);
-        /* Recaclulate  Splines  */
+        /* Recalculate  Splines  */
         if (c_useAtomDataPrefetch)
         {
             // charges
index 9575aaf2ff36b6ded5229070a2ef0faa64ce3d58..c67e471ca3c86118b89d4061e046c8b824bebe1d 100644 (file)
@@ -94,7 +94,7 @@
 /*! \brief
  * CUDA only
  * Atom limit above which it is advantageous to turn on the
- * recalcuating of the splines in the gather and using less threads per atom in the spline and spread
+ * recalculating of the splines in the gather and using less threads per atom in the spline and spread
  */
 constexpr int c_pmeGpuPerformanceAtomLimit = 23000;
 
index 0b7d03054a337e33a14923e81d6fc940d5314cb2..7d21c03d5214725c8c4fe71d5d1f137ca01add28 100644 (file)
@@ -105,7 +105,7 @@ void warning_error(warninp_t wi, const std::string& s);
  * This is intended for use where there is no way to produce a data
  * structure that would prevent execution from segfaulting. */
 [[noreturn]] void warning_error_and_exit(warninp_t wi, const char* s, int f_errno, const char* file, int line);
-//! \copydoc warning_error_and_exit(warninp_t, const char *, int, const char *, int);
+//! \copydoc warning_error_and_exit(warninp_t,const char *,int,const char *,int)
 [[noreturn]] void
 warning_error_and_exit(warninp_t wi, const std::string& s, int f_errno, const char* file, int line);
 
index 565c2c1bc84ac64ca29f3ef538c567db57849879..584edc7775f1def740132f9427fcbde10385745e 100644 (file)
@@ -60,7 +60,7 @@
  *
  * \tparam        ValueType            Raw value type of the \p buffer.
  * \param[in,out] buffer               Pointer to the device-side buffer.
- * \param[in]     numValues            Number of values to accomodate.
+ * \param[in]     numValues            Number of values to accommodate.
  * \param[in]     deviceContext        The buffer's dummy device  context - not managed explicitly in CUDA RT.
  */
 template<typename ValueType>
index 227370968f5dcf97fa98f4debe75efe5a70d4dd7..b8e047a87defc8156778493199f23d71cfa805cd 100644 (file)
@@ -60,7 +60,7 @@
  *
  * \tparam        ValueType            Raw value type of the \p buffer.
  * \param[in,out] buffer               Pointer to the device-side buffer.
- * \param[in]     numValues            Number of values to accomodate.
+ * \param[in]     numValues            Number of values to accommodate.
  * \param[in]     deviceContext        The buffer's device context-to-be.
  */
 template<typename ValueType>
index b01c0a18b2421bd62c09a4f2f9f991c07b70627a..4daf42387421e4ebd7167e3c4b6f9cdabdfb2d96 100644 (file)
@@ -2041,7 +2041,7 @@ pdihs(int             nbonds,
             }
         }
 
-        /* Caclulate GMX_SIMD_REAL_WIDTH dihedral angles at once */
+        /* Calculate GMX_SIMD_REAL_WIDTH dihedral angles at once */
         dih_angle_simd(x, ai, aj, ak, al, pbc_simd, &phi_S, &mx_S, &my_S, &mz_S, &nx_S, &ny_S,
                        &nz_S, &nrkj_m2_S, &nrkj_n2_S, &p_S, &q_S);
 
@@ -2157,7 +2157,7 @@ rbdihs(int             nbonds,
             }
         }
 
-        /* Caclulate GMX_SIMD_REAL_WIDTH dihedral angles at once */
+        /* Calculate GMX_SIMD_REAL_WIDTH dihedral angles at once */
         dih_angle_simd(x, ai, aj, ak, al, pbc_simd, &phi_S, &mx_S, &my_S, &mz_S, &nx_S, &ny_S,
                        &nz_S, &nrkj_m2_S, &nrkj_n2_S, &p_S, &q_S);
 
index 0ba9878dbeaff47db11096088cf971643cad0cc0..b3c869463934222e3be7052656cbce593132d70a 100644 (file)
@@ -64,7 +64,7 @@ public:
      * \param[in] kernelShapeParameters determine the shape of the spreading kernel
      */
     explicit Impl(const GaussianSpreadKernelParameters::Shape& kernelShapeParameters);
-    //! \copydoc DensityFittingForce::evaluateForce(const DensitySpreadKernelParameters::PositionAndAmplitude & localParameters, basic_mdspan<const float, dynamicExtents3D> densityDerivative)
+    //! \copydoc DensityFittingForce::evaluateForce
     RVec evaluateForce(const GaussianSpreadKernelParameters::PositionAndAmplitude& localParameters,
                        basic_mdspan<const float, dynamicExtents3D> densityDerivative);
     //! The width of the Gaussian in lattice spacing units
index 6c199bc03e5c71d2126750836c8c800fdbd2c3a2..47aa53240f868aae5313eefd6ddc99bee9d4da4d 100644 (file)
@@ -228,7 +228,7 @@ public:
     //! \}
 
     PaddedVector() : storage_(), unpaddedEnd_(begin()) {}
-    /*! \brief Constructor that specifes the initial size. */
+    /*! \brief Constructor that specifies the initial size. */
     explicit PaddedVector(size_type count, const allocator_type& allocator = Allocator()) :
         storage_(count, allocator),
         unpaddedEnd_(begin() + count)
@@ -237,7 +237,7 @@ public:
         // the padding elements are added
         resizeWithPadding(count);
     }
-    /*! \brief Constructor that specifes the initial size and an element to copy. */
+    /*! \brief Constructor that specifies the initial size and an element to copy. */
     explicit PaddedVector(size_type count, value_type const& v, const allocator_type& allocator = Allocator()) :
         storage_(count, v, allocator),
         unpaddedEnd_(begin() + count)
index 7666ec6d3309b5b8918a43be9b6f247d0b82f469..ec8b3e1eb95529fcecbddfbca0bddeecb9d51baa 100644 (file)
@@ -636,9 +636,9 @@ std::remove_const_t<T> norm2(T* v)
 {
     return ::norm2(v);
 }
+/*! \} */
 
 } // namespace gmx
 
-/*! \} */
 
 #endif
index b4c08e0e350850531aa6c3adf358368eac849e0d..1b5ec5f42b93caf299b6dc8dd89679bb15fd12bc 100644 (file)
@@ -69,7 +69,7 @@ namespace gmx
 
 /*!\brief Number of CUDA threads in a block
  *
- * \todo Check if using smaller block size will lead to better prformance.
+ * \todo Check if using smaller block size will lead to better performance.
  */
 constexpr static int c_threadsPerBlock = 256;
 //! Maximum number of threads in a block (for __launch_bounds__)
index 8d7a4bba153eed5da15f960f9a61871a283f7b38..b9dd8632db293e8a7ad3e60e72ab0d1601ced86c 100644 (file)
@@ -72,7 +72,7 @@ namespace gmx
 {
 /*!\brief Number of CUDA threads in a block
  *
- * \todo Check if using smaller block size will lead to better prformance.
+ * \todo Check if using smaller block size will lead to better performance.
  */
 constexpr static int c_threadsPerBlock = 256;
 //! Maximum number of threads in a block (for __launch_bounds__)
@@ -163,7 +163,7 @@ void UpdateConstrainGpu::Impl::scaleCoordinates(const matrix scalingMatrix)
     launchGpuKernel(scaleCoordinates_kernel, coordinateScalingKernelLaunchConfig_, deviceStream_,
                     nullptr, "scaleCoordinates_kernel", kernelArgs);
     // TODO: Although this only happens on the pressure coupling steps, this synchronization
-    //       can affect the perfornamce if nstpcouple is small.
+    //       can affect the performance if nstpcouple is small.
     deviceStream_.synchronize();
 }
 
@@ -182,7 +182,7 @@ void UpdateConstrainGpu::Impl::scaleVelocities(const matrix scalingMatrix)
     launchGpuKernel(scaleCoordinates_kernel, coordinateScalingKernelLaunchConfig_, deviceStream_,
                     nullptr, "scaleCoordinates_kernel", kernelArgs);
     // TODO: Although this only happens on the pressure coupling steps, this synchronization
-    //       can affect the perfornamce if nstpcouple is small.
+    //       can affect the performance if nstpcouple is small.
     deviceStream_.synchronize();
 }
 
index 3362a410db3c7fd50ec1a92e6ff6985f9a505d60..0df65f2bc55f327269619062f81785a5b7315a5e 100644 (file)
@@ -52,7 +52,7 @@
 #include "pairlist.h"
 
 
-/*! \copybrief Returns the base-2 log of n.
+/*! \brief Returns the base-2 log of n.
  * *
  * Generates a fatal error when n is not an integer power of 2.
  */
index 600bd20a62d7e27165604de21e2a6d6efd8b6298..b18d16a7a46a2ed2b874bcad2038d44df3c6edc3 100644 (file)
@@ -288,7 +288,8 @@ void nbnxn_gpu_init_x_to_nbat_x(const Nbnxm::GridSet gmx_unused& gridSet,
  * \param[in,out] gpu_nbv          The nonbonded data GPU structure.
  * \param[in]     d_x              Device-side coordinates in plain rvec format.
  * \param[in]     xReadyOnDevice   Event synchronizer indicating that the coordinates are ready in
- * the device memory. \param[in]     locality         Copy coordinates for local or non-local atoms.
+ * the device memory.
+ * \param[in]     locality         Copy coordinates for local or non-local atoms.
  * \param[in]     gridId           Index of the grid being converted.
  * \param[in]     numColumnsMax    Maximum number of columns in the grid.
  */
index 47cfa5b81f47c494a1a9a77caf6dc7c49e6f4aa7..6e0d94ca2bd64780a89710e280af7661f9b115fb 100644 (file)
@@ -82,7 +82,7 @@ void init_ewald_coulomb_force_table(const EwaldCorrectionTables& tables,
                          tables.tableF.size(), deviceContext);
 }
 
-void inline printEnviromnentVariableDeprecationMessage(bool               isEnvironmentVariableSet,
+void inline printEnvironmentVariableDeprecationMessage(bool               isEnvironmentVariableSet,
                                                        const std::string& environmentVariableSuffix)
 {
     if (isEnvironmentVariableSet)
@@ -111,9 +111,9 @@ int nbnxn_gpu_pick_ewald_kernel_type(const interaction_const_t& ic)
     const bool forceTwinCutoffEwaldLegacy = (getenv("GMX_CUDA_NB_EWALD_TWINCUT") != nullptr)
                                             || (getenv("GMX_OCL_NB_EWALD_TWINCUT") != nullptr);
 
-    printEnviromnentVariableDeprecationMessage(forceAnalyticalEwaldLegacy, "NB_ANA_EWALD");
-    printEnviromnentVariableDeprecationMessage(forceTabulatedEwaldLegacy, "NB_TAB_EWALD");
-    printEnviromnentVariableDeprecationMessage(forceTwinCutoffEwaldLegacy, "NB_EWALD_TWINCUT");
+    printEnvironmentVariableDeprecationMessage(forceAnalyticalEwaldLegacy, "NB_ANA_EWALD");
+    printEnvironmentVariableDeprecationMessage(forceTabulatedEwaldLegacy, "NB_TAB_EWALD");
+    printEnvironmentVariableDeprecationMessage(forceTwinCutoffEwaldLegacy, "NB_EWALD_TWINCUT");
 
     const bool forceAnalyticalEwald =
             (getenv("GMX_GPU_NB_ANA_EWALD") != nullptr) || forceAnalyticalEwaldLegacy;
index 886298a20efeb06fda1cf12b8b3877a0da5d63ca..a517c2fd04eb3a0539e582fcd4d4cd28cacffa05 100644 (file)
@@ -69,7 +69,6 @@ struct gmx_wallclock_gpu_nbnxn_t;
 //! Define 1/sqrt(pi)
 #define M_FLOAT_1_SQRTPI 0.564189583547756f
 
-/*! @} */
 /*! \brief Constants for platform-dependent defaults for the prune kernel's j4 processing concurrency.
  *
  *  Initialized using macros that can be overridden at compile-time (using #GMX_NBNXN_PRUNE_KERNEL_J4_CONCURRENCY).
index 2a0c75784a93de6f2f8580a1ea7983829fb3a57c..9825a1b80390b9f446313a9259fc136af3a57b22 100644 (file)
@@ -76,16 +76,14 @@ public:
     /*!
      * \brief Wrap a restraint potential as an MDModule
      *
-     * \param restraint shared ownership of an object for calculating restraint forces.
-     * \return new wrapper object sharing ownership of restraint.
-     *
      * Consumers of the interfaces provided by an IMDModule do not extend the lifetime
      * of the interface objects returned by mdpOptionProvider(), outputProvider(), or
      * registered via initForceProviders(). Calling code must keep this object alive
      * as long as those interfaces are needed (probably the duration of an MD run).
      *
-     * \param restraint handle to object to wrap
+     * \param restraint shared ownership of an object for calculating restraint forces
      * \param sites list of sites for the framework to pass to the restraint
+     * \return new wrapper object sharing ownership of restraint
      */
     static std::unique_ptr<RestraintMDModule> create(std::shared_ptr<gmx::IRestraintPotential> restraint,
                                                      const std::vector<int>& sites);
index 60fa0634b3f7a27ae872721eafcb01208d9ea806..d8a698e393fe67fbd774c91b4adfc0aacfabe732 100644 (file)
@@ -1,7 +1,7 @@
 /*
  * This file is part of the GROMACS molecular simulation package.
  *
- * Copyright (c) 2014,2015,2016,2017,2019, by the GROMACS development team, led by
+ * Copyright (c) 2014,2015,2016,2017,2019,2020, by the GROMACS development team, led by
  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
  * and including many others, as listed in the AUTHORS file in the
  * top-level source directory and at http://www.gromacs.org.
@@ -68,7 +68,7 @@ namespace gmx
 /*! \addtogroup module_simd */
 /*! \{ */
 
-/* \name SIMD implementation data types
+/*! \name SIMD implementation data types
  * \{
  */
 
index 6b0a943abbdc7e80c622d4025541a0f5230fd2ee..b0ed1105bcb6b345812e43bfd7e1313cf2caf9f5 100644 (file)
@@ -1,7 +1,7 @@
 /*
  * This file is part of the GROMACS molecular simulation package.
  *
- * Copyright (c) 2014,2015,2016,2017,2019, by the GROMACS development team, led by
+ * Copyright (c) 2014,2015,2016,2017,2019,2020, by the GROMACS development team, led by
  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
  * and including many others, as listed in the AUTHORS file in the
  * top-level source directory and at http://www.gromacs.org.
@@ -66,7 +66,7 @@ namespace gmx
 /*! \addtogroup module_simd */
 /*! \{ */
 
-/* \name SIMD implementation data types and built-in conversions between types
+/*! \name SIMD implementation data types and built-in conversions between types
  * \{
  */
 
index 4c2df75fc8c189d701162a242801d4448defdf39..7c051f7e1c64c7145de8a9015d2a28eb02ed12a8 100644 (file)
@@ -68,7 +68,7 @@ namespace gmx
 /*! \addtogroup module_simd */
 /*! \{ */
 
-/* \name Higher-level SIMD utility functions, double precision.
+/*! \name Higher-level SIMD utility functions, double precision.
  *
  * These include generic functions to work with triplets of data, typically
  * coordinates, and a few utility functions to load and update data in the
index 99919f322301e6023988b4f9b8d214a935c5d202..5e2ac95fd5154398add59961cb43bd7f667c96bd 100644 (file)
@@ -68,7 +68,7 @@ namespace gmx
 /*! \addtogroup module_simd */
 /*! \{ */
 
-/* \name Higher-level SIMD utility functions, single precision.
+/*! \name Higher-level SIMD utility functions, single precision.
  *
  * These include generic functions to work with triplets of data, typically
  * coordinates, and a few utility functions to load and update data in the
index 536d14675c1c6996ba1b7cb72b9a83c584a4035e..55fd89f55fd679d5d20a7c7ca4183e5d75f08e53 100644 (file)
@@ -602,7 +602,7 @@ static inline SimdSetZeroProxy gmx_simdcall setZero()
 
 namespace internal
 {
-// TODO: Don't foward function but properly rename them and use proper traits
+// TODO: Don't forward function but properly rename them and use proper traits
 template<typename T>
 struct Simd4Traits
 {
@@ -756,7 +756,7 @@ using Simd4NReal = Simd4NFloat;
 
 } // namespace gmx
 
-// \}          end of module_simd
+//! \}          end of module_simd
 
 //! \endcond   end of condition libapi
 
index d5dfec2ac173d25db335982fda997215c7d783fa..1c435b8abbe322683196e83a3c2f6de64436e5c3 100644 (file)
@@ -5050,7 +5050,7 @@ static inline SimdFloat gmx_simdcall expSingleAccuracy(SimdFloat x)
 
 /*! \brief SIMD pow(x,y), only targeting single accuracy.
  *
- * \copydetails pow(SimdFloat)
+ * \copydetails pow(SimdFloat,SimdFloat)
  */
 template<MathOptimization opt = MathOptimization::Safe>
 static inline SimdFloat gmx_simdcall powSingleAccuracy(SimdFloat x, SimdFloat y)
index 20d7b916dbdf47b26b305a2806a8b3d355de9db4..07b25cde5f5849241f25d2377b33b3ff41750e03 100644 (file)
@@ -448,14 +448,13 @@ void SimdMathTest::generateTestPointsTest()
 
 // Actual math function tests below
 
-
-namespace
-{
-
 /*! \cond internal */
 /*! \addtogroup module_simd */
 /*! \{ */
 
+namespace
+{
+
 // Reference data is selected based on test name, so make the test name precision-dependent
 #        if GMX_DOUBLE
 TEST_F(SimdMathTest, generateTestPointsDouble)
index 5eacdcb672fc1e63e2fbaa497440e4404b770dce..138bffc8f3cdb32870ce2907454462bd95c59297 100644 (file)
@@ -293,7 +293,14 @@ private:
     iterator end_;
 };
 
-//! \copydoc ArrayRef::fromArray()
+/*! \brief
+ * Constructs a reference to a C array.
+ *
+ * \param[in] begin  Pointer to the beginning of array.
+ * \param[in] size   Number of elements in array.
+ *
+ * Passed array must remain valid for the lifetime of this object.
+ */
 //! \related ArrayRef
 template<typename T>
 ArrayRef<T> arrayRefFromArray(T* begin, size_t size)
@@ -301,7 +308,7 @@ ArrayRef<T> arrayRefFromArray(T* begin, size_t size)
     return ArrayRef<T>(begin, begin + size);
 }
 
-//! \copydoc ArrayRef::fromArray()
+//! \copydoc arrayRefFromArray
 //! \related ArrayRef
 template<typename T>
 ArrayRef<const T> constArrayRefFromArray(const T* begin, size_t size)