Add docstrings

modules/plugin/chowdsp_fuzzy_search/Search/chowdsp_DatabaseWordStorage.h

@@ -2,9 +2,10 @@
 
 namespace chowdsp::search_database
 {
-/** helper struct to store words in "flat" memory */
+/** Storage for a set of words in "flat" memory */
 struct WordStorage
 {
+    /** A "view" into a word in the flat buffer */
     struct WordView
     {
         uint32_t start = 0;
@@ -14,13 +15,18 @@ struct WordStorage
     std::vector<char> wordData {}; // all characters from a word, in order in memory
     std::vector<search_helpers::WordHist> wordHist {}; // a tiny histogram per word
     std::vector<WordView> wordViewList {}; // map to find index from word
-    std::unordered_map<std::string, size_t> wordMap;
+    std::unordered_map<std::string, size_t> wordMap {};
 
+    /**
+     * Gets a std::string_view from a WordView.
+     * This method does not perform any additional validation.
+     */
     [[nodiscard]] std::string_view getString (WordView wordView) const noexcept
     {
         return { wordData.data() + wordView.start, wordView.end - wordView.start };
     }
 
+    /** Clears the storage. */
     void clear()
     {
         wordData.clear();
@@ -29,16 +35,22 @@ struct WordStorage
         wordMap.clear();
     }
 
+    /** Reserves memory for a given number of words. */
     void reserve (size_t wordCount)
     {
-        wordData.reserve (wordCount * 8);
+        wordData.reserve (wordCount * 8); // assuming ~8 characters per word
         wordHist.reserve (wordCount);
         wordViewList.reserve (wordCount);
         wordMap.reserve (wordCount);
     }
 
+    /** Returns the number of words currently in storage. */
     [[nodiscard]] auto getWordCount() const noexcept { return wordViewList.size(); }
 
+    /**
+     * Adds a word to the storage, and returns the "index"
+     * at which the word can be found in the `wordViewList`.
+     */
     [[nodiscard]] int addWord (std::string_view word)
     {
         // if exist, return index

modules/plugin/chowdsp_fuzzy_search/Search/chowdsp_SearchDatabase.h

@@ -5,13 +5,24 @@
 
 namespace chowdsp
 {
+/**
+ * A search database containing a series of tagged entries.
+ *
+ * The user can add entries to the database at any time using `addEntry()`.
+ * Once the database has been filled, the user can enter "search" mode by
+ * calling `prepareForSearch()`, and then call `search` as needed to retrieve search results.
+ *
+ * Note that `prepareForSearch()` must be called before calling `search()`,
+ * after new entries are added to the database.
+ *
+ * \tparam Key The "key" type used by the database.
+ * \tparam numFields The number of "tag" fields that each entry has.
+ */
 template <typename Key = std::string, size_t numFields = 1>
 class SearchDatabase
 {
 public:
-    // ------------------------------------------------------
-    // public struct, used for returning the results
-
+    /** The result type returned to the user. */
     struct Result
     {
         Key key;
@@ -82,11 +93,11 @@ class SearchDatabase
     struct Entry
     {
         Key key;
-        SmallVector<WordFromField, numFields * 5> words; // index into words from strings
+        SmallVector<WordFromField, numFields * 5> words {}; // index into words from strings
     };
 
     // =======================================================
-    search_database::WordStorage wordStorage;
+    search_database::WordStorage wordStorage {};
     std::vector<Entry> entries;
     std::array<float, numFields> fieldWeights;
     float threshold = 0.1f;
@@ -221,7 +232,7 @@ class SearchDatabase
         }
     }
 
-    std::string_view copy_string (std::string_view s) const
+    [[nodiscard]] std::string_view copy_string (std::string_view s) const
     {
         auto* sc_data = searchArena.allocate<char> (s.size());
         std::copy (s.begin(), s.end(), sc_data);
@@ -234,6 +245,7 @@ class SearchDatabase
         resetEntries();
     }
 
+    /** Clears any entries currently in the database. */
     void resetEntries (size_t entriesToReserve = 100, size_t wordsToReserve = 1000, size_t arenaSize = 1 << 14)
     {
         wordStorage.clear();
@@ -247,6 +259,7 @@ class SearchDatabase
         searchArena.reset (arenaSize);
     }
 
+    /** Prepares the database to process new search queries. */
     void prepareForSearch()
     {
         const auto numBytesNeededForSearch =
@@ -258,6 +271,7 @@ class SearchDatabase
         searchArena.reset (numBytesNeededForSearch);
     }
 
+    /** Adds a new entry to the database. */
     void addEntry (Key key, const std::array<std::string_view, numFields>& fields)
     {
         // create entry
@@ -312,25 +326,29 @@ class SearchDatabase
         entries.push_back (e);
     }
 
+    /** Returns the number of entries currently stored in the database. */
     auto countEntries() const
     {
         return entries.size();
     }
 
-    // each field can have a weight
+    /** Sets the "weights" given to each field. */
     void setWeights (const std::array<float, numFields>& newFieldWeights)
     {
         fieldWeights = newFieldWeights;
     }
 
-    // any search-result scoring below this will not be returned from the search
+    /** Any search-result scoring below the threshold will not be returned from the search. */
     void setThreshold (float newThreshold)
     {
         threshold = newThreshold;
     }
 
-    // returns a big list of results ( sorted and with a score )
-    nonstd::span<const Result> search (std::string_view queryString) const
+    /**
+     * Returns a list of search results (sorted and with a score).
+     * Note that the list is only valid until the next call to `search()`.
+     */
+    [[nodiscard]] nonstd::span<const Result> search (std::string_view queryString) const
     {
         if (queryString.size() > 100)
             return {}; // upper bound!