Merge pull request PointCloudLibrary#4678 from mvieth/documentation6

Improve documentation, fix warnings

Author: mvieth

common/include/pcl/common/common.h

@@ -60,6 +60,7 @@ namespace pcl
   /** \brief Compute the smallest angle between two 3D vectors in radians (default) or degree.
     * \param v1 the first 3D vector (represented as a \a Eigen::Vector4f)
     * \param v2 the second 3D vector (represented as a \a Eigen::Vector4f)
+    * \param in_degree determine if angle should be in radians or degrees
     * \return the angle between v1 and v2 in radians or degrees
     * \note Handles rounding error for parallel and anti-parallel vectors
     * \ingroup common

common/include/pcl/point_cloud.h

@@ -536,6 +536,7 @@ namespace pcl
        * \note This breaks the organized structure of the cloud by setting the height to
        * 1!
        * \param[in] count new size of the point cloud
+       * \param[in] value value each point of the cloud should have
        */
       inline void
       assign(index_t count, const PointT& value)
@@ -549,6 +550,7 @@ namespace pcl
        * \brief Replaces the points with `new_width * new_height` copies of `value`
        * \param[in] new_width new width of the point cloud
        * \param[in] new_height new height of the point cloud
+       * \param[in] value value each point of the cloud should have
        */
       inline void
       assign(index_t new_width, index_t new_height, const PointT& value)
@@ -580,6 +582,7 @@ namespace pcl
        * `*this`
        * \note This calculates the height based on size and width provided. This means
        * the assignment happens even if the size is not perfectly divisible by width
+       * \param[in] first, last the range from which the points are copied
        * \param[in] new_width new width of the point cloud
        */
       template <class InputIterator>
@@ -616,6 +619,7 @@ namespace pcl
        * \brief Replaces the points with the elements from the initializer list `ilist`
        * \note This calculates the height based on size and width provided. This means
        * the assignment happens even if the size is not perfectly divisible by width
+       * \param[in] ilist initializer list from which the points are copied
        * \param[in] new_width new width of the point cloud
        */
       void

doc/advanced/content/c_cache.rst

@@ -35,14 +35,14 @@ Install ``colorgcc`` on an Ubuntu system with ::
 
 To enable colorgcc, perform the following steps:
 
-.. code-block:: cmake
+.. code-block:: shell
 
   cp /etc/colorgcc/colorgccrc $HOME/.colorgccrc
 
 
 * edit the $HOME/.colorgccrc file, search for the following lines:
 
-.. code-block:: cmake
+.. code-block:: text
 
     g++: /usr/bin/g++
     gcc: /usr/bin/gcc
@@ -54,7 +54,7 @@ To enable colorgcc, perform the following steps:
 
 and replace them with:
 
-.. code-block:: cmake
+.. code-block:: text
 
     g++: ccache /usr/bin/g++
     gcc: ccache /usr/bin/gcc
@@ -66,7 +66,7 @@ and replace them with:
 
 * create a $HOME/bin or $HOME/sbin directory, and create the following softlinks in it
 
-.. code-block:: cmake
+.. code-block:: shell
 
     ln -s /usr/bin/colorgcc c++
     ln -s /usr/bin/colorgcc cc

doc/tutorials/content/function_filter.rst

@@ -1,4 +1,4 @@
-.. _conditional_removal:
+.. _function_filter:
 
 Removing outliers using a custom non-destructive condition
 ----------------------------------------------------------
@@ -7,7 +7,7 @@ This document demonstrates how to use the FunctionFilter class to remove points
 and faster appraoch compared to ConditionalRemoval filter or a `custom Condition class <https://cpp-optimizations.netlify.app/pcl_filter/>`_.
 
 .. note::
-Advanced users can use the FunctorFilter class that can provide a small but measurable speedup when used with a `lambda <https://en.cppreference.com/w/cpp/language/lambda>`_.
+   Advanced users can use the FunctorFilter class that can provide a small but measurable speedup when used with a `lambda <https://en.cppreference.com/w/cpp/language/lambda>`_.
 
 The code
 --------

doc/tutorials/content/how_features_work.rst

@@ -54,13 +54,13 @@ the table below for a reference on each of the terms used.
 +=============+================================================+
 | Foo         | a class named `Foo`                            |
 +-------------+------------------------------------------------+
-| FooPtr      | a shared pointer to a class `Foo`,       |
+| FooPtr      | a shared pointer to a class `Foo`,             |
 |             |                                                | 
-|             | e.g., `shared_ptr<Foo>`                 |
+|             | e.g., `shared_ptr<Foo>`                        |
 +-------------+------------------------------------------------+
-| FooConstPtr | a const shared pointer to a class `Foo`, |
+| FooConstPtr | a const shared pointer to a class `Foo`,       |
 |             |                                                |
-|             | e.g., `const shared_ptr<const Foo>`     |
+|             | e.g., `const shared_ptr<const Foo>`            |
 +-------------+------------------------------------------------+
 
 How to pass the input

doc/tutorials/content/random_sample_consensus.rst

@@ -10,7 +10,7 @@ Theoretical Primer
 
 The abbreviation of "RANdom SAmple Consensus" is RANSAC, and it is an iterative method that is used to estimate parameters of a mathematical model from a set of data containing outliers.  This algorithm was published by Fischler and Bolles in 1981.  The RANSAC algorithm assumes that all of the data we are looking at is comprised of both inliers and outliers.  Inliers can be explained by a model with a particular set of parameter values, while outliers do not fit that model in any circumstance.  Another necessary assumption is that a procedure which can optimally estimate the parameters of the chosen model from the data is available.
 
-From [Wikipedia]_:
+From [WikipediaRANSAC]_:
 
   *The input to the RANSAC algorithm is a set of observed data values, a parameterized model which can explain or be fitted to the observations, and some confidence parameters.*
 
@@ -38,7 +38,7 @@ From [Wikipedia]_:
    :align: right
    :height: 200px
 
-The pictures to the left and right (From [Wikipedia]_) show a simple application of the RANSAC algorithm on a 2-dimensional set of data. The image on our left is a visual representation of a data set containing both inliers and outliers.  The image on our right shows all of the outliers in red, and shows inliers in blue.  The blue line is the result of the work done by RANSAC.  In this case the model that we are trying to fit to the data is a line, and it looks like it's a fairly good fit to our data.
+The pictures to the left and right (From [WikipediaRANSAC]_) show a simple application of the RANSAC algorithm on a 2-dimensional set of data. The image on our left is a visual representation of a data set containing both inliers and outliers.  The image on our right shows all of the outliers in red, and shows inliers in blue.  The blue line is the result of the work done by RANSAC.  In this case the model that we are trying to fit to the data is a line, and it looks like it's a fairly good fit to our data.
 
 The code
 --------
@@ -123,4 +123,4 @@ It will show you the result of applying RandomSampleConsensus to this data set w
    :align: center
    :height: 400px
 
-.. [Wikipedia] http://en.wikipedia.org/wiki/RANSAC
+.. [WikipediaRANSAC] http://en.wikipedia.org/wiki/RANSAC

gpu/octree/include/pcl/gpu/octree/octree.hpp

@@ -150,7 +150,7 @@ namespace pcl
             /** \brief Batch approximate nearest search on GPU
               * \param[in] queries array of centers
               * \param[out] result array of results ( one index for each query )
-              * \param[out] sqr_distances corresponding square distances to results from query point
+              * \param[out] sqr_distance corresponding square distances to results from query point
               */
             void approxNearestSearch(const Queries& queries, NeighborIndices& result, ResultSqrDists& sqr_distance) const;
 

registration/include/pcl/registration/correspondence_estimation_organized_projection.h

@@ -187,15 +187,21 @@ class CorrespondenceEstimationOrganizedProjection
   }
 
   /** \brief Computes the correspondences, applying a maximum Euclidean distance
-   * threshold. \param correspondences \param[in] max_distance Euclidean distance
-   * threshold above which correspondences will be rejected
+   * threshold.
+   * \param[out] correspondences the found correspondences (index of query point, index
+   * of target point, distance)
+   * \param[in] max_distance Euclidean distance threshold above which correspondences
+   * will be rejected
    */
   void
   determineCorrespondences(Correspondences& correspondences, double max_distance);
 
   /** \brief Computes the correspondences, applying a maximum Euclidean distance
-   * threshold. \param correspondences \param[in] max_distance Euclidean distance
-   * threshold above which correspondences will be rejected
+   * threshold.
+   * \param[out] correspondences the found correspondences (index of query and target
+   * point, distance)
+   * \param[in] max_distance Euclidean distance threshold above which correspondences
+   * will be rejected
    */
   void
   determineReciprocalCorrespondences(Correspondences& correspondences,

registration/include/pcl/registration/gicp.h

@@ -186,10 +186,11 @@ class GeneralizedIterativeClosestPoint
   /** \brief Estimate a rigid rotation transformation between a source and a target
    * point cloud using an iterative non-linear Levenberg-Marquardt approach. \param[in]
    * cloud_src the source point cloud dataset \param[in] indices_src the vector of
-   * indices describing the points of interest in \a cloud_src \param[in] cloud_tgt the
-   * target point cloud dataset \param[in] indices_tgt the vector of indices describing
-   * the correspondences of the interest points from \a indices_src \param[out]
-   * transformation_matrix the resultant transformation matrix
+   * indices describing the points of interest in \a cloud_src
+   * \param[in] cloud_tgt the target point cloud dataset
+   * \param[in] indices_tgt the vector of indices describing
+   * the correspondences of the interest points from \a indices_src
+   * \param[out] transformation_matrix the resultant transformation matrix
    */
   void
   estimateRigidTransformationBFGS(const PointCloudSource& cloud_src,
@@ -275,7 +276,7 @@ class GeneralizedIterativeClosestPoint
   }
 
   /** \brief Set the minimal translation gradient threshold for early optimization stop
-   * \param[in] translation gradient threshold in meters
+   * \param[in] tolerance translation gradient threshold in meters
    */
   void
   setTranslationGradientTolerance(double tolerance)
@@ -293,7 +294,7 @@ class GeneralizedIterativeClosestPoint
   }
 
   /** \brief Set the minimal rotation gradient threshold for early optimization stop
-   * \param[in] rotation gradient threshold in radians
+   * \param[in] tolerance rotation gradient threshold in radians
    */
   void
   setRotationGradientTolerance(double tolerance)

registration/include/pcl/registration/transformation_estimation.h

@@ -93,8 +93,8 @@ class TransformationEstimation {
    * indices_src the vector of indices describing the points of interest in \a cloud_src
    * \param[in] cloud_tgt the target point cloud dataset
    * \param[in] indices_tgt the vector of indices describing the correspondences of the
-   * interest points from \a indices_src \param[out] transformation_matrix the resultant
-   * transformation matrix
+   * interest points from \a indices_src
+   * \param[out] transformation_matrix the resultant transformation matrix
    */
   virtual void
   estimateRigidTransformation(const pcl::PointCloud<PointSource>& cloud_src,

registration/include/pcl/registration/transformation_estimation_2D.h

@@ -80,9 +80,9 @@ class TransformationEstimation2D
 
   /** \brief Estimate a rigid transformation between a source and a target point cloud
    * in 2D. \param[in] cloud_src the source point cloud dataset \param[in] indices_src
-   * the vector of indices describing the points of interest in \a cloud_src \param[in]
-   * cloud_tgt the target point cloud dataset \param[out] transformation_matrix the
-   * resultant transformation matrix
+   * the vector of indices describing the points of interest in \a cloud_src
+   * \param[in] cloud_tgt the target point cloud dataset
+   * \param[out] transformation_matrix the resultant transformation matrix
    */
   inline void
   estimateRigidTransformation(const pcl::PointCloud<PointSource>& cloud_src,
@@ -92,9 +92,10 @@ class TransformationEstimation2D
 
   /** \brief Estimate a rigid transformation between a source and a target point cloud
    * in 2D. \param[in] cloud_src the source point cloud dataset \param[in] indices_src
-   * the vector of indices describing the points of interest in \a cloud_src \param[in]
-   * cloud_tgt the target point cloud dataset \param[in] indices_tgt the vector of
-   * indices describing the correspondences of the interest points from \a indices_src
+   * the vector of indices describing the points of interest in \a cloud_src
+   * \param[in] cloud_tgt the target point cloud dataset
+   * \param[in] indices_tgt the vector of  indices describing the correspondences of the
+   * interest points from \a indices_src
    * \param[out] transformation_matrix the resultant transformation matrix
    */
   virtual void

registration/include/pcl/registration/transformation_estimation_3point.h

@@ -100,8 +100,8 @@ class TransformationEstimation3Point
    * indices_src the vector of indices describing the points of interest in \a cloud_src
    * \param[in] cloud_tgt the target point cloud dataset
    * \param[in] indices_tgt the vector of indices describing the correspondences of the
-   * interest points from \a indices_src \param[out] transformation_matrix the resultant
-   * transformation matrix
+   * interest points from \a indices_src
+   * \param[out] transformation_matrix the resultant transformation matrix
    */
   void
   estimateRigidTransformation(const pcl::PointCloud<PointSource>& cloud_src,

registration/include/pcl/registration/transformation_estimation_dq.h

@@ -83,8 +83,9 @@ class TransformationEstimationDQ
   /** \brief Estimate a rigid rotation transformation between a source and a target
    * point cloud using dual quaternion optimization \param[in] cloud_src the source
    * point cloud dataset \param[in] indices_src the vector of indices describing the
-   * points of interest in \a cloud_src \param[in] cloud_tgt the target point cloud
-   * dataset \param[out] transformation_matrix the resultant transformation matrix
+   * points of interest in \a cloud_src
+   * \param[in] cloud_tgt the target point cloud dataset
+   * \param[out] transformation_matrix the resultant transformation matrix
    */
   inline void
   estimateRigidTransformation(const pcl::PointCloud<PointSource>& cloud_src,
@@ -95,10 +96,11 @@ class TransformationEstimationDQ
   /** \brief Estimate a rigid rotation transformation between a source and a target
    * point cloud using dual quaternion optimization \param[in] cloud_src the source
    * point cloud dataset \param[in] indices_src the vector of indices describing the
-   * points of interest in \a cloud_src \param[in] cloud_tgt the target point cloud
-   * dataset \param[in] indices_tgt the vector of indices describing the correspondences
-   * of the interest points from \a indices_src \param[out] transformation_matrix the
-   * resultant transformation matrix
+   * points of interest in \a cloud_src
+   * \param[in] cloud_tgt the target point cloud dataset
+   * \param[in] indices_tgt the vector of indices describing the correspondences of the
+   * interest points from \a indices_src
+   * \param[out] transformation_matrix the resultant transformation matrix
    */
   inline void
   estimateRigidTransformation(const pcl::PointCloud<PointSource>& cloud_src,

registration/include/pcl/registration/transformation_estimation_dual_quaternion.h

@@ -80,8 +80,9 @@ class TransformationEstimationDualQuaternion
   /** \brief Estimate a rigid rotation transformation between a source and a target
    * point cloud using dual quaternion optimization \param[in] cloud_src the source
    * point cloud dataset \param[in] indices_src the vector of indices describing the
-   * points of interest in \a cloud_src \param[in] cloud_tgt the target point cloud
-   * dataset \param[out] transformation_matrix the resultant transformation matrix
+   * points of interest in \a cloud_src
+   * \param[in] cloud_tgt the target point cloud dataset
+   * \param[out] transformation_matrix the resultant transformation matrix
    */
   inline void
   estimateRigidTransformation(const pcl::PointCloud<PointSource>& cloud_src,
@@ -92,10 +93,11 @@ class TransformationEstimationDualQuaternion
   /** \brief Estimate a rigid rotation transformation between a source and a target
    * point cloud using dual quaternion optimization \param[in] cloud_src the source
    * point cloud dataset \param[in] indices_src the vector of indices describing the
-   * points of interest in \a cloud_src \param[in] cloud_tgt the target point cloud
-   * dataset \param[in] indices_tgt the vector of indices describing the correspondences
-   * of the interest points from \a indices_src \param[out] transformation_matrix the
-   * resultant transformation matrix
+   * points of interest in \a cloud_src
+   * \param[in] cloud_tgt the target point cloud dataset
+   * \param[in] indices_tgt the vector of indices describing the correspondences of the
+   * interest points from \a indices_src
+   * \param[out] transformation_matrix the resultant transformation matrix
    */
   inline void
   estimateRigidTransformation(const pcl::PointCloud<PointSource>& cloud_src,

registration/include/pcl/registration/transformation_estimation_lm.h

@@ -119,8 +119,9 @@ class TransformationEstimationLM
   /** \brief Estimate a rigid rotation transformation between a source and a target
    * point cloud using LM. \param[in] cloud_src the source point cloud dataset
    * \param[in] indices_src the vector of indices describing the points of interest in
-   * \a cloud_src \param[in] cloud_tgt the target point cloud dataset \param[out]
-   * transformation_matrix the resultant transformation matrix
+   * \a cloud_src
+   * \param[in] cloud_tgt the target point cloud dataset
+   * \param[out] transformation_matrix the resultant transformation matrix
    */
   inline void
   estimateRigidTransformation(const pcl::PointCloud<PointSource>& cloud_src,
@@ -131,10 +132,11 @@ class TransformationEstimationLM
   /** \brief Estimate a rigid rotation transformation between a source and a target
    * point cloud using LM. \param[in] cloud_src the source point cloud dataset
    * \param[in] indices_src the vector of indices describing the points of interest in
-   * \a cloud_src \param[in] cloud_tgt the target point cloud dataset \param[in]
-   * indices_tgt the vector of indices describing the correspondences of the interest
-   * points from \a indices_src \param[out] transformation_matrix the resultant
-   * transformation matrix
+   * \a cloud_src
+   * \param[in] cloud_tgt the target point cloud dataset
+   * \param[in] indices_tgt the vector of indices describing the correspondences of the
+   * interest points from \a indices_src
+   * \param[out] transformation_matrix the resultant transformation matrix
    */
   inline void
   estimateRigidTransformation(const pcl::PointCloud<PointSource>& cloud_src,

registration/include/pcl/registration/transformation_estimation_point_to_plane_lls.h

@@ -87,8 +87,9 @@ class TransformationEstimationPointToPlaneLLS
   /** \brief Estimate a rigid rotation transformation between a source and a target
    * point cloud using SVD. \param[in] cloud_src the source point cloud dataset
    * \param[in] indices_src the vector of indices describing the points of interest in
-   * \a cloud_src \param[in] cloud_tgt the target point cloud dataset \param[out]
-   * transformation_matrix the resultant transformation matrix
+   * \a cloud_src
+   * \param[in] cloud_tgt the target point cloud dataset
+   * \param[out] transformation_matrix the resultant transformation matrix
    */
   inline void
   estimateRigidTransformation(const pcl::PointCloud<PointSource>& cloud_src,
@@ -99,10 +100,11 @@ class TransformationEstimationPointToPlaneLLS
   /** \brief Estimate a rigid rotation transformation between a source and a target
    * point cloud using SVD. \param[in] cloud_src the source point cloud dataset
    * \param[in] indices_src the vector of indices describing the points of interest in
-   * \a cloud_src \param[in] cloud_tgt the target point cloud dataset \param[in]
-   * indices_tgt the vector of indices describing the correspondences of the interest
-   * points from \a indices_src \param[out] transformation_matrix the resultant
-   * transformation matrix
+   * \a cloud_src
+   * \param[in] cloud_tgt the target point cloud dataset
+   * \param[in] indices_tgt the vector of indices describing the correspondences of the
+   * interest points from \a indices_src
+   * \param[out] transformation_matrix the resultant transformation matrix
    */
   inline void
   estimateRigidTransformation(const pcl::PointCloud<PointSource>& cloud_src,