Improvements to the Doxygen configuration:

- Exclude internal-only SPTree.hpp.
- Added knncolle tagfile for nice links.
- Minor clean-ups to various docstrings.

.github/workflows/doxygenate.yaml

@@ -16,6 +16,11 @@ jobs:
       with:
         args: -O docs/doxygen-awesome.css https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/main/doxygen-awesome.css
 
+    - name: Add knncolle tagfile
+      uses: wei/wget@v1
+      with:
+        args: -O docs/knncolle.tag https://knncolle.github.io/knncolle/knncolle.tag
+
     - name: Doxygen Action
       uses: mattnotmitt/doxygen-action@v1
       with:

docs/Doxyfile

@@ -917,7 +917,11 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../include/qdtsne \
+INPUT                  = ../include/qdtsne/qdtsne.hpp \
+                         ../include/qdtsne/Options.hpp \
+                         ../include/qdtsne/Status.hpp \
+                         ../include/qdtsne/initialize.hpp \
+                         ../include/qdtsne/utils.hpp \
                          ../README.md
 
 # This tag can be used to specify the character encoding of the source files
@@ -2370,13 +2374,13 @@ SKIP_FUNCTION_MACROS   = YES
 # the path). If a tag file is not located in the directory in which doxygen is
 # run, you must also specify the path to the tagfile here.
 
-TAGFILES               =
+TAGFILES               = knncolle.tag=https://knncolle.github.io/knncolle/
 
 # When a file name is specified after GENERATE_TAGFILE, doxygen will create a
 # tag file that is based on the input files it reads. See section "Linking to
 # external documentation" for more information about the usage of tag files.
 
-GENERATE_TAGFILE       =
+GENERATE_TAGFILE       = html/qdtsne.tag
 
 # If the ALLEXTERNALS tag is set to YES, all external class will be listed in
 # the class index. If set to NO, only the inherited external classes will be

include/qdtsne/Options.hpp

@@ -3,14 +3,13 @@
 
 /**
  * @file Options.hpp
- *
  * @brief Options for the t-SNE algorithm.
  */
 
 namespace qdtsne {
 
 /**
- * @param Options for `initialize()`.
+ * @brief Options for `initialize()`.
  */
 struct Options {
     /**

include/qdtsne/Status.hpp

@@ -45,13 +45,13 @@
 
 /**
  * @file Status.hpp
- * @brief Status of the t-SNE algorithm.
+ * @brief Status of the t-SNE iterations.
  */
 
 namespace qdtsne {
 
 /**
- * @brief Current status of the t-SNE iterations.
+ * @brief Status of the t-SNE iterations.
  *
  * @tparam num_dim_ Number of dimensions in the t-SNE embedding.
  * @tparam Index_ Integer type for the neighbor indices.

include/qdtsne/utils.hpp

@@ -27,7 +27,7 @@ using NeighborList = std::vector<std::vector<std::pair<Index_, Float_> > >;
 
 /**
  * Determines the appropriate number of neighbors, given a perplexity value.
- * Useful when the neighbor search is conducted outside of the `Tsne` class.
+ * Useful when the neighbor search is conducted outside of `initialize()`.
  *
  * @param perplexity Perplexity to use in the t-SNE algorithm.
  * @return Number of nearest neighbors to find.
@@ -44,16 +44,16 @@ inline int perplexity_to_k(double perplexity) {
  * @tparam num_dim_ Number of embedding dimensions.
  * @tparam Float_ Floating-point type to use for the calculations.
  *
- * @param[out] Y Pointer to a 2D array with number of rows and columns equal to `num_dim` and N`, respectively.
+ * @param[out] Y Pointer to a 2D array with number of rows and columns equal to `num_dim` and `num_points`, respectively.
  * On output, `Y` is filled with random draws from a standard normal distribution. 
- * @param N Number of observations.
+ * @param num_points Number of points in the embedding.
  * @param seed Seed for the random number generator.
  */
 template<int num_dim_, typename Float_ = double>
 void initialize_random(Float_* Y, size_t N, int seed = 42) {
     std::mt19937_64 rng(seed);
 
-    size_t total = N * num_dim_;
+    size_t total = num_pts * num_dim_;
     bool odd = total % 2;
     if (odd) {
         --total;
@@ -81,15 +81,15 @@ void initialize_random(Float_* Y, size_t N, int seed = 42) {
  * @tparam num_dim_ Number of embedding dimensions.
  * @tparam Float_ Floating-point type to use for the calculations.
  *
- * @param N Number of observations.
+ * @param num_points Number of observations.
  * @param seed Seed for the random number generator.
  *
- * @return A vector of length `N * num_dim_` containing random draws from a standard normal distribution. 
+ * @return A vector of length `num_points * num_dim_` containing random draws from a standard normal distribution. 
  */
 template<int num_dim_, typename Float_ = double>
-std::vector<Float_> initialize_random(size_t N, int seed = 42) {
-    std::vector<Float_> Y(num_dim_ * N);
-    initialize_random<num_dim_>(Y.data(), N, seed);
+std::vector<Float_> initialize_random(size_t num_points, int seed = 42) {
+    std::vector<Float_> Y(num_dim_ * num_points);
+    initialize_random<num_dim_>(Y.data(), num_points, seed);
     return Y;
 }