From 580c501c2929e6d5e9a3fd4dc6b2809e092e9ed5 Mon Sep 17 00:00:00 2001
From: Krishna Vedala <7001608+kvedala@users.noreply.github.com>
Date: Tue, 16 Jun 2020 08:13:02 -0400
Subject: [PATCH] updated documentations

(cherry picked from commit 05b3dbdab9b6df041ac17af89610c5b018adeed2)
---
 machine_learning/kohonen_som_topology.c | 38 +++----------------------
 1 file changed, 4 insertions(+), 34 deletions(-)

diff --git a/machine_learning/kohonen_som_topology.c b/machine_learning/kohonen_som_topology.c
index 0c37c3cb..f318e91e 100644
--- a/machine_learning/kohonen_som_topology.c
+++ b/machine_learning/kohonen_som_topology.c
@@ -16,6 +16,7 @@
  * \warning MSVC 2019 compiler generates code that does not execute as expected.
  * However, MinGW, Clang for GCC and Clang for MSVC compilers on windows perform
  * as expected. Any insights and suggestions should be directed to the author.
+ * \see kohonen_som_trace.c
  */
 #define _USE_MATH_DEFINES /**< required for MS Visual C */
 #include <math.h>
@@ -219,6 +220,7 @@ void get_min_2d(double **X, int N, double *val, int *x_idx, int *y_idx)
  * \param[in] num_features number of features per input sample
  * \param[in] alpha learning rate \f$0<\alpha\le1\f$
  * \param[in] R neighborhood range
+ * \returns minimum distance of sample and trained weights
  */
 double update_weights(const double *X, struct array_3d *W, double **D,
                       int num_out, int num_features, double alpha, int R)
@@ -308,7 +310,8 @@ void kohonen_som(double **X, struct array_3d *W, int num_samples,
     for (int i = 0; i < num_out; i++)
         D[i] = (double *)malloc(num_out * sizeof(double));
 
-    double dmin = 1.f;
+    double dmin = 1.f; // average minimum distance of all samples
+
     // Loop alpha from 1 to slpha_min
     for (double alpha = 1.f; alpha > alpha_min && dmin > 1e-3;
          alpha -= 0.001, iter++)
@@ -385,17 +388,6 @@ void test_2d_classes(double *const *data, int N)
  * * `test1.csv`: random test samples points with a circular pattern
  * * `w11.csv`: initial random map
  * * `w12.csv`: trained SOM map
- *
- * The outputs can be readily plotted in [gnuplot](https:://gnuplot.info) using
- * the following snippet
- * ```gnuplot
- * set datafile separator ','
- * plot "test1.csv" title "original", \
- *      "w11.csv" title "w1", \
- *      "w12.csv" title "w2"
- * ```
- * ![Sample execution
- * output](https://raw.githubusercontent.com/kvedala/C/docs/images/machine_learning/kohonen/test1.svg)
  */
 void test1()
 {
@@ -496,17 +488,6 @@ void test_3d_classes1(double *const *data, int N)
  * * `test2.csv`: random test samples points with a lamniscate pattern
  * * `w21.csv`: initial random map
  * * `w22.csv`: trained SOM map
- *
- * The outputs can be readily plotted in [gnuplot](https:://gnuplot.info) using
- * the following snippet
- * ```gnuplot
- * set datafile separator ','
- * plot "test2.csv" title "original", \
- *      "w21.csv" title "w1", \
- *      "w22.csv" title "w2"
- * ```
- * ![Sample execution
- * output](https://raw.githubusercontent.com/kvedala/C/docs/images/machine_learning/kohonen/test2.svg)
  */
 void test2()
 {
@@ -610,17 +591,6 @@ void test_3d_classes2(double *const *data, int N)
  * * `test3.csv`: random test samples points with a circular pattern
  * * `w31.csv`: initial random map
  * * `w32.csv`: trained SOM map
- *
- * The outputs can be readily plotted in [gnuplot](https:://gnuplot.info) using
- * the following snippet
- * ```gnuplot
- * set datafile separator ','
- * plot "test3.csv" title "original", \
- *      "w31.csv" title "w1", \
- *      "w32.csv" title "w2"
- * ```
- * ![Sample execution
- * output](https://raw.githubusercontent.com/kvedala/C/docs/images/machine_learning/kohonen/test3.svg)
  */
 void test3()
 {