From 7d9c8be36f832a242836d197412cb97cdf49079f Mon Sep 17 00:00:00 2001
From: Chris Cromer <chris@cromer.cl>
Date: Sat, 10 Dec 2022 16:26:30 -0300
Subject: [PATCH] document the knowledge base

---
 src/knowledge_base.h | 123 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 120 insertions(+), 3 deletions(-)

diff --git a/src/knowledge_base.h b/src/knowledge_base.h
index d3ce8ba..2970df3 100644
--- a/src/knowledge_base.h
+++ b/src/knowledge_base.h
@@ -17,54 +17,171 @@ namespace obelisk
     class KnowledgeBase
     {
         private:
-            const int DEFAULT_FLAGS
-                = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE;
+            /**
+             * @brief The filename of the opened knowledge base.
+             *
+             */
             const char* filename_;
+
+            /**
+             * @brief The SQLite connection handle.
+             *
+             */
             sqlite3* dbConnection_ = nullptr;
+
+            /**
+             * @brief The user passed flags to use when opening the database.
+             *
+             */
             int flags_;
 
+            /**
+             * @brief Enable foreign key functionality in the open database.
+             *
+             * This must always be done when the connection is opened or it will not
+             * enforce the foreign key constraints.
+             */
             void enableForeignKeys();
+
+            /**
+             * @brief Create the tables in the database.
+             *
+             * @param[in] function This function is called to create the table.
+             */
             void createTable(std::function<const char*()> function);
 
         public:
+            /**
+             * @brief Construct a new Knowledge Base object.
+             *
+             * @param[in] filename The name of the file to save the knowledge base as.
+             * @param[in] flags The flags to open the knowledge base with.
+             */
             KnowledgeBase(const char* filename, int flags);
 
+            /**
+             * @brief Construct a new Knowledge Base object.
+             *
+             * @param[in] filename The name of the file to save the knowledge base as.
+             */
             KnowledgeBase(const char* filename) :
                 KnowledgeBase(filename,
                     SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE)
             {
             }
 
+            /**
+             * @brief Destroy the Knowledge Base object.
+             *
+             * This will close the opened knowledge base before destroying it.
+             */
             ~KnowledgeBase();
 
+            /**
+             * @brief Add entities to the knowledge base.
+             *
+             * @todo make entities const?
+             * @param[in] entities The entities to add.
+             */
             void addEntities(std::vector<obelisk::Entity>& entities);
+
+            /**
+             * @brief Add verbs to the knowledge base.
+             *
+             * @param[in] verbs The verbs to add.
+             */
             void addVerbs(std::vector<obelisk::Verb>& verbs);
+
+            /**
+             * @brief Add facts to the database.
+             *
+             * @param[in] facts The facts to add.
+             */
             void addFacts(std::vector<obelisk::Fact>& facts);
 
+            /**
+             * @brief Get an entity object based on the ID it contains.
+             *
+             * @param[out] entity The Entity object should contain just the ID and the rest will be filled in.
+             */
             void getEntity(obelisk::Entity& entity);
+
+            /**
+             * @brief Get a verb object based on the ID it contains.
+             *
+             * @param[in] verb The Verb object should contain just the ID and the rest will be filled in.
+             */
             void getVerb(obelisk::Verb& verb);
+
+            /**
+             * @brief Get a fact object based on the ID it contains.
+             *
+             * @param[in] fact The fact object should contain just the ID and the rest will be filled in.
+             */
             void getFact(obelisk::Fact& fact);
 
-            void getDouble(double& result, float var1, float var2);
+            /**
+             * @brief Take a float and divide it into 2 floats.
+             *
+             * This is useful to store doubles in SQLite since SQLite doesn't have a double type.
+             * Instead just store the 2 floats in the database. Then after selecting them combine them.
+             *
+             * @param[out] result1 The first float generated from the double.
+             * @param[out] result2 The second float generated from the double.
+             * @param[in] var The double to split into the 2 floats.
+             */
             void getFloat(float& result1, float& result2, double var);
+
+            /**
+             * @brief Combines 2 separated floats back into a double.
+             *
+             * This will recombine the separated floats from the getFloat method.
+             *
+             * @param[out] result The double generated from the combined floats.
+             * @param[in] var1 The first float to combine.
+             * @param[in] var2 The second float to combine.
+             */
+            void getDouble(double& result, float var1, float var2);
     };
 
+    /**
+     * @brief Exception thrown by the KnowledgeBase.
+     *
+     */
     class KnowledgeBaseException : public std::exception
     {
         private:
+            /**
+             * @brief The error message given.
+             *
+             */
             const std::string errorMessage_;
 
         public:
+            /**
+             * @brief Construct a new Knowledge Base Exception object.
+             *
+             */
             KnowledgeBaseException() :
                 errorMessage_("an unknown error ocurred")
             {
             }
 
+            /**
+             * @brief Construct a new Knowledge Base Exception object.
+             *
+             * @param[in] errorMessage The error message given when thrown.
+             */
             KnowledgeBaseException(const std::string& errorMessage) :
                 errorMessage_(errorMessage)
             {
             }
 
+            /**
+             * @brief Get the error message that occurred.
+             *
+             * @return const char* Returns the error message.
+             */
             const char* what() const noexcept
             {
                 return errorMessage_.c_str();