Add documentation

source/armarx/navigation/human/CombinedDistance.h

+/**
+ * This file is part of ArmarX.
+ *
+ * ArmarX is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ *
+ * ArmarX is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ * @author     Timo Weberruß ( timo dot weberruss at student dot kit dot edu )
+ * @date       2022
+ * @copyright  http://www.gnu.org/licenses/gpl-2.0.txt
+ *             GNU General Public License
+ */
+
+
 #pragma once
 
 #include "DistanceFunction.h"
@@ -7,9 +29,21 @@
 
 namespace armarx::navigation::human
 {
+    /**
+     * @brief The CombinedDistance class combines the standard euclidean distance multiplicatively
+     * with an orientation distance in such a way that the distance is always at least the euclidean
+     * distance but will be scaled by up to the maximum influence factor if the people face away
+     * from each other.
+     */
     class CombinedDistance : public DistanceFunction
     {
     public:
+
+        /**
+         * @brief CombinedDistance Creates a new combined distance with the specified orientation scale factor
+         * @param maxOrientationInfluence the euclidean distance between the humans will be scaled
+         * by up to this factor if they face away from each other
+         */
         CombinedDistance(double maxOrientationInfluence);
         virtual double computeDistance(Human &h1, Human &h2);
 

source/armarx/navigation/human/DistanceFunction.h

+/**
+ * This file is part of ArmarX.
+ *
+ * ArmarX is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ *
+ * ArmarX is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ * @author     Timo Weberruß ( timo dot weberruss at student dot kit dot edu )
+ * @date       2022
+ * @copyright  http://www.gnu.org/licenses/gpl-2.0.txt
+ *             GNU General Public License
+ */
+
 #pragma once
 
 #include <armarx/navigation/human/types.h>
@@ -5,11 +26,24 @@
 
 namespace armarx::navigation::human
 {
+    /**
+     * @brief A distance function is able to compute a distance between two humans.
+     * The exact semantics of this distance depends on the implementation. For example,
+     * a HumanGrouper uses distances two group humans together (the smaller the distance between
+     * two humans, the more likely it is for them to belong to the same social group).
+     */
     class DistanceFunction
     {
     public:
         DistanceFunction();
         virtual ~DistanceFunction();
+
+        /**
+         * @brief computeDistance computes the (semantic or literal, depending on the implementation) distance between the given humans
+         * @param h1 the first human
+         * @param h2 the second human
+         * @return the distance between the humans (greater values correspond to humans that are further away)
+         */
         virtual double computeDistance(Human &h1, Human &h2) = 0;
     };
 }

source/armarx/navigation/human/EuclideanDistance.h

+/**
+ * This file is part of ArmarX.
+ *
+ * ArmarX is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ *
+ * ArmarX is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ * @author     Timo Weberruß ( timo dot weberruss at student dot kit dot edu )
+ * @date       2022
+ * @copyright  http://www.gnu.org/licenses/gpl-2.0.txt
+ *             GNU General Public License
+ */
+
 #pragma once
 
 #include "DistanceFunction.h"
@@ -5,6 +26,10 @@
 
 namespace armarx::navigation::human
 {
+    /**
+     * @brief The EuclideanDistance class is an implementation of a distance function that computes
+     * the literal, euclidean distance between two human. (i.e. sqrt(dx²+dy²)).
+     */
     class EuclideanDistance : public DistanceFunction
     {
     public:

source/armarx/navigation/human/OrientationDistance.h

+/**
+ * This file is part of ArmarX.
+ *
+ * ArmarX is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ *
+ * ArmarX is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ * @author     Timo Weberruß ( timo dot weberruss at student dot kit dot edu )
+ * @date       2022
+ * @copyright  http://www.gnu.org/licenses/gpl-2.0.txt
+ *             GNU General Public License
+ */
+
 #pragma once
 
 #include "DistanceFunction.h"
@@ -5,9 +26,26 @@
 
 namespace armarx::navigation::human
 {
+    /**
+     * @brief The OrientationDistance class is a DistanceFunction that computes the distance between
+     * the two humans based upon their orientation towards or away from each other.
+     *
+     * This distance function will return
+     * - the specified minimum distance (0 by default) if the humans are exactly facing each other
+     * - the specified maximum distance (1 by default) if the humans are oriented back to back
+     * - a linear interpolation between the two for anything inbetween (for instance, two people
+     *   looking in the same direction will have a distance equal to the arithmetic mean of the
+     *   minimum and maximum distance, 0.5 by default)
+     */
     class OrientationDistance : public DistanceFunction
     {
     public:
+
+        /**
+         * @brief OrientationDistance Creates a new OrientationDistance with the specified range
+         * @param max the distance two people will have when faced back to back
+         * @param min the distance two people will have when oriented face to face
+         */
         OrientationDistance(double max = 1, double min = 0);
         virtual double computeDistance(Human &h1, Human &h2);
     private: