#579: [C/C++ pyclustering] Doxygen documentation.

annoviko · May 30, 2020 · ac62a6b · ac62a6b
1 parent 7f264aa
commit ac62a6b
Show file tree

Hide file tree

Showing 14 changed files with 299 additions and 156 deletions.
diff --git a/ccore/include/pyclustering/cluster/hsyncnet.hpp b/ccore/include/pyclustering/cluster/hsyncnet.hpp
@@ -26,6 +26,7 @@
 
 #include <vector>
 
+#include <pyclustering/definitions.hpp>
 #include <pyclustering/cluster/syncnet.hpp>
 
 
@@ -39,6 +40,15 @@ typedef ensemble_data<hsyncnet_cluster>     hsyncnet_cluster_data;
 typedef syncnet_analyser                    hsyncnet_analyser;
 
 
+/*!
+
+@class   hsyncnet hsyncnet.hpp pyclustering/cluster/hsyncnet.hpp
+
+@brief   Oscillatory neural network based on Kuramoto model for cluster analysis.
+
+@see hsyncnet_analyser
+
+*/
 class hsyncnet: public syncnet {
 private:
     std::size_t m_number_clusters;
@@ -51,19 +61,54 @@ class hsyncnet: public syncnet {
     const static std::size_t    DEFAULT_INCREASE_STEP;
 
 public:
-    hsyncnet(std::vector<std::vector<double> > * input_data, 
+    /*!
+
+    @brief    Constructor of HSyncNet (Hierarchical Sync Network) algorithm.
+
+    @param[in] input_data: input data for cluster analysis.
+    @param[in] cluster_number: amount of clusters that should be allocated.
+    @param[in] initial_phases: initial phases for oscillators.
+
+    */
+    hsyncnet(dataset * input_data, 
         const std::size_t cluster_number, 
         const initial_type initial_phases);
 
-    hsyncnet(std::vector<std::vector<double> > * input_data,
+    /*!
+
+    @brief    Constructor of HSyncNet (Hierarchical Sync Network) algorithm.
+
+    @param[in] input_data: input data for cluster analysis.
+    @param[in] cluster_number: amount of clusters that should be allocated.
+    @param[in] initial_phases: initial phases for oscillators.
+    @param[in] initial_neighbors: defines initial connectivity-radius by average distance to connect specified amount of oscillators (points).
+    @param[in] increase_persent: percent of increasing of connectivity-radius on each iteration (input values in range (0.0; 1.0) correspond to (0%; 100%)).
+    
+    */
+    hsyncnet(dataset * input_data,
         const std::size_t cluster_number,
         const initial_type initial_phases,
         const std::size_t initial_neighbors,
         const double increase_persent);
 
+    /*!
+
+    @brief    Default destructor of HSyncNet (Hierarchical Sync Network) algorithm.
+
+    */
     virtual ~hsyncnet() = default;
 
 public:
+    /*!
+
+    @brief Performs cluster analysis by the network simulation.
+
+    @param[in]  order: order of synchronization that is used as indication for stopping processing, the `order` value should be in range `(0, 1)`.
+    @param[in]  solver: specified type of solving diff. equation.
+    @param[in]  collect_dynamic: specified requirement to collect whole dynamic of the network.
+    @param[out] analyser: analyser of sync results of clustering.
+
+    */
     virtual void process(const double order, const solve_type solver, const bool collect_dynamic, hsyncnet_analyser & analyser) override;
 
 private:

diff --git a/ccore/include/pyclustering/cluster/kmeans.hpp b/ccore/include/pyclustering/cluster/kmeans.hpp
@@ -41,7 +41,7 @@ namespace clst {
 
 /*!
 
-@class    kmeans kmeans.hpp pyclustering/interface/kmeans.hpp
+@class    kmeans kmeans.hpp pyclustering/cluster/kmeans.hpp
 
 @brief    Represents K-Means clustering algorithm for cluster analysis.
 @details  The algorithm related to partitional class when input data is divided into groups.

diff --git a/ccore/include/pyclustering/cluster/kmedians.hpp b/ccore/include/pyclustering/cluster/kmedians.hpp
@@ -47,9 +47,9 @@ namespace clst {
 */
 class kmedians {
 public:
-    const static double         DEFAULT_TOLERANCE;
+    const static double         DEFAULT_TOLERANCE;  /**< Default value of the tolerance stop condition: if maximum value of change of centers of clusters is less than tolerance then algorithm stops processing. */
 
-    const static std::size_t    DEFAULT_ITERMAX;
+    const static std::size_t    DEFAULT_ITERMAX;    /**< Default value of the step stop condition - maximum number of iterations that is used for clustering process. */
 
 private:
     const static double         THRESHOLD_CHANGE;
@@ -105,18 +105,18 @@ class kmedians {
     * @brief    Performs cluster analysis of an input data.
     *
     * @param[in]  p_data: input data for cluster analysis.
-    * @param[out] p_result: clustering result of an input data.
+    * @param[out] p_output_result: clustering result of an input data.
     *
     */
-    void process(const dataset & data, kmedians_data & output_result);
+    void process(const dataset & p_data, kmedians_data & p_output_result);
 
 private:
     /**
     *
     * @brief    Updates clusters in line with current medians.
     *
-    * @param[in] medians: medians that are used for updating clusters.
-    * @param[out] clusters: updated clusters in line with the specified medians.
+    * @param[in] p_medians: medians that are used for updating clusters.
+    * @param[out] p_clusters: updated clusters in line with the specified medians.
     *
     */
     void update_clusters(const dataset & p_medians, cluster_sequence & p_clusters);

diff --git a/ccore/include/pyclustering/cluster/kmedoids.hpp b/ccore/include/pyclustering/cluster/kmedoids.hpp
@@ -53,9 +53,9 @@ enum class kmedoids_data_t {
 */
 class kmedoids {
 public:
-    static const double      DEFAULT_TOLERANCE;
+    static const double      DEFAULT_TOLERANCE;     /**< Default value of the tolerance stop condition: if maximum value of change of centers of clusters is less than tolerance then algorithm stops processing. */
 
-    static const std::size_t DEFAULT_ITERMAX;
+    static const std::size_t DEFAULT_ITERMAX;       /**< Default value of the step stop condition - maximum number of iterations that is used for clustering process. */
 
 private:
     static const std::size_t OBJECT_ALREADY_CONTAINED;

diff --git a/ccore/include/pyclustering/cluster/syncnet.hpp b/ccore/include/pyclustering/cluster/syncnet.hpp
@@ -41,7 +41,9 @@ using syncnet_cluster       = std::vector<std::size_t>;
 using syncnet_cluster_data  = ensemble_data<syncnet_cluster>;
 
 
-/*
+/*!
+
+@class   syncnet_analyser syncnet.hpp pyclustering/cluster/syncnet.hpp
 
 @brief   Analyser for syncnet - oscillatory neural network based on Kuramoto model for cluster analysis.
 
@@ -50,16 +52,37 @@ using syncnet_cluster_data  = ensemble_data<syncnet_cluster>;
 */
 class syncnet_analyser: public sync_dynamic {
 public:
+    /*!
+    
+    @brief  Default constructor of the output dynamic of Sync network.
+    
+    */
     syncnet_analyser() = default;
 
+    /*!
+
+    @brief  Default destructor of the output dynamic of Sync network.
+
+    */
     virtual ~syncnet_analyser() = default;
 
 public:
+    /*!
+
+    @brief      Performs analysis of the output dynamic in order to obtain clusters.
+    @details    Allocated clusters are placed to output argument `data`.
+
+    @param[in]  eps: tolerance that defines the maximum difference between phases of oscillators that belong to one cluster.
+    @param[out] data: allocated clusters during the analysis of the output dynamic.
+
+    */
     void allocate_clusters(const double eps, syncnet_cluster_data & data);
 };
 
 
-/*
+/*!
+
+@class   syncnet syncnet.hpp pyclustering/cluster/syncnet.hpp
 
 @brief   Oscillatory neural network based on Kuramoto model for cluster analysis.
 
@@ -68,12 +91,11 @@ class syncnet_analyser: public sync_dynamic {
  */
 class syncnet: public sync_network {
 protected:
-    std::vector<std::vector<double> >    * oscillator_locations;
-    std::vector<std::vector<double> >    * distance_conn_weights;
-    double                                connection_weight;
+    std::vector<std::vector<double> >    * oscillator_locations;    /**< Spatial location of each oscillator. */
+    std::vector<std::vector<double> >    * distance_conn_weights;   /**< Weight of each connection in the network. */
 
 public:
-    /*
+    /*!
     
     @brief   Contructor of the adapted oscillatory network SYNC for cluster analysis.
     
@@ -87,7 +109,7 @@ class syncnet: public sync_network {
     */
     syncnet(std::vector<std::vector<double> > * input_data, const double connectivity_radius, const bool enable_conn_weight, const initial_type initial_phases);
 
-    /*
+    /*!
     
     @brief   Copy-contructor of the sync-net algorithm is forbidden.
     
@@ -103,19 +125,19 @@ class syncnet: public sync_network {
     */
     virtual ~syncnet();
 
-    /*
+    /*!
     
-    @brief Network is trained via achievement sync state between the oscillators using the radius of coupling.
+    @brief Performs cluster analysis by the network simulation.
     
-    @param[in]  order: order of synchronization that is used as indication for stopping processing.
-    @param[in]  solver: specified type of solving diff. equation. 
+    @param[in]  order: order of synchronization that is used as indication for stopping processing, the `order` value should be in range `(0, 1)`.
+    @param[in]  solver: specified type of solving diff. equation.
     @param[in]  collect_dynamic: specified requirement to collect whole dynamic of the network.
     @param[out] analyser: analyser of sync results of clustering.
     
     */
     virtual void process(const double order, const solve_type solver, const bool collect_dynamic, syncnet_analyser & analyser);
 
-    /*
+    /*!
     
     @brief   Overrided method for calculation of oscillator phase.
     
@@ -131,7 +153,7 @@ class syncnet: public sync_network {
     virtual void phase_kuramoto_equation(const double t, const differ_state<double> & inputs, const differ_extra<void *> & argv, differ_state<double> & outputs) const override;
 
 public:
-    /*
+    /*!
     
     @brief   Assignment operator for the sync-net algorithm is forbidden.
     
@@ -141,7 +163,7 @@ class syncnet: public sync_network {
     syncnet & operator=(const syncnet & p_other) = delete;
 
 protected:
-    /*
+    /*!
     
     @brief   Create connections between oscillators in line with input radius of connectivity.
     

diff --git a/ccore/include/pyclustering/nnet/pcnn.hpp b/ccore/include/pyclustering/nnet/pcnn.hpp
@@ -1,23 +1,24 @@
-/**
-*
-* @authors Andrei Novikov (pyclustering@yandex.ru)
-* @date 2014-2020
-* @copyright GNU Public License
-*
-* GNU_PUBLIC_LICENSE
-*   pyclustering is free software: you can redistribute it and/or modify
-*   it under the terms of the GNU General Public License as published by
-*   the Free Software Foundation, either version 3 of the License, or
-*   (at your option) any later version.
-*
-*   pyclustering 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/>.
-*
+/*!
+
+@authors Andrei Novikov (pyclustering@yandex.ru)
+@date 2014-2020
+@copyright GNU Public License
+
+@cond GNU_PUBLIC_LICENSE
+    pyclustering is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    pyclustering 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/>.
+@endcond
+
 */
 
 #pragma once

diff --git a/ccore/include/pyclustering/nnet/som.hpp b/ccore/include/pyclustering/nnet/som.hpp
@@ -1,23 +1,24 @@
-/**
-*
-* @authors Andrei Novikov (pyclustering@yandex.ru)
-* @date 2014-2020
-* @copyright GNU Public License
-*
-* GNU_PUBLIC_LICENSE
-*   pyclustering is free software: you can redistribute it and/or modify
-*   it under the terms of the GNU General Public License as published by
-*   the Free Software Foundation, either version 3 of the License, or
-*   (at your option) any later version.
-*
-*   pyclustering 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/>.
-*
+/*!
+
+@authors Andrei Novikov (pyclustering@yandex.ru)
+@date 2014-2020
+@copyright GNU Public License
+
+@cond GNU_PUBLIC_LICENSE
+    pyclustering is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    pyclustering 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/>.
+@endcond
+
 */
 
 #pragma once
@@ -146,9 +147,9 @@ class som {
      *
      * @brief   Constructor of self-organized map.
      *
-     * @param[in] rows: number of neurons in the column (number of rows).
-     * @param[in] cols: number of neurons in the row (number of columns).
-     * @param[in] conn_type: type of connection between oscillators in the network.
+     * @param[in] num_rows: number of neurons in the column (number of rows).
+     * @param[in] num_cols: number of neurons in the row (number of columns).
+     * @param[in] type_conn: type of connection between oscillators in the network.
      * @param[in] parameters: others parameters of the network.
      *
      */