Add documentation for c++ API

src/include/main/client_context.h

@@ -7,13 +7,21 @@
 namespace kuzu {
 namespace main {
 
-// Contain client side configuration.
-// We make profiler associated per query, so profiler is not maintained in client context.
+/**
+ * @brief Contain client side configuration. We make profiler associated per query, so profiler is
+ * not maintained in client context.
+ */
 class ClientContext {
     friend class Connection;
 
 public:
+    /**
+     * @brief Constructs the ClientContext object.
+     */
     KUZU_API explicit ClientContext();
+    /**
+     * @brief Deconstructs the ClientContext object.
+     */
     KUZU_API ~ClientContext() = default;
 
 private:

src/include/main/connection.h

@@ -8,6 +8,10 @@
 namespace kuzu {
 namespace main {
 
+/**
+ * @brief Connection is used to interact with a Database instance. Each Connection is thread-safe.
+ * Multiple connections can connect to the same Database instance in a multi-threaded environment.
+ */
 class Connection {
     friend class kuzu::testing::ApiTest;
     friend class kuzu::testing::BaseGraphTest;
@@ -33,32 +37,98 @@ class Connection {
     enum class ConnectionTransactionMode : uint8_t { AUTO_COMMIT = 0, MANUAL = 1 };
 
 public:
+    /**
+     * @brief Creates a connection to the database.
+     * @param database A pointer to the database instance that this connection will be connected to.
+     */
     KUZU_API explicit Connection(Database* database);
+    /**
+     * @brief Destructs the connection.
+     */
     KUZU_API ~Connection();
-
+    /**
+     * @brief Manually starts a new read-only transaction in the current connection and sets the
+     * current transaction mode to MANUAL.
+     */
     KUZU_API void beginReadOnlyTransaction();
+    /**
+     * @brief Manually starts a new write transaction in the current connection and sets the current
+     * transaction mode to MANUAL.
+     */
     KUZU_API void beginWriteTransaction();
+    /**
+     * @brief Manually commits the current transaction and sets the current transaction mode to
+     * AUTO_COMMIT.
+     */
     KUZU_API void commit();
+    /**
+     * @brief Manually rollbacks the current transaction and sets the current transaction mode to
+     * AUTO_COMMIT.
+     */
     KUZU_API void rollback();
+    /**
+     * @brief Sets the maximum number of threads to use for execution in the current connection.
+     * @param numThreads The number of threads to use for execution in the current connection.
+     */
     KUZU_API void setMaxNumThreadForExec(uint64_t numThreads);
+    /**
+     * @brief Returns the maximum number of threads to use for execution in the current connection.
+     * @return The maximum number of threads to use for execution in the current connection.
+     */
     KUZU_API uint64_t getMaxNumThreadForExec();
+    /**
+     * @brief Executes the given query and returns the result.
+     * @param query The query to execute.
+     * @return The result of the query.
+     */
     KUZU_API std::unique_ptr<QueryResult> query(const std::string& query);
+    /**
+     * @brief Prepares the given query and returns the prepared statement.
+     * @param query The query to prepare.
+     * @return The prepared statement.
+     */
     KUZU_API std::unique_ptr<PreparedStatement> prepare(const std::string& query);
-
+    /**
+     * @brief Executes the given prepared statement with args and returns the result.
+     * @param preparedStatement The prepared statement to execute.
+     * @param args The parameter pack where each arg is a std::pair with the first element being
+     * parameter name and second element being parameter value.
+     * @return The result of the query.
+     */
     KUZU_API template<typename... Args>
     inline std::unique_ptr<QueryResult> execute(
         PreparedStatement* preparedStatement, std::pair<std::string, Args>... args) {
         std::unordered_map<std::string, std::shared_ptr<common::Value>> inputParameters;
         return executeWithParams(preparedStatement, inputParameters, args...);
     }
-    // Note: Any call that goes through executeWithParams acquires a lock in the end by calling
-    // executeLock(...).
+    /**
+     * @brief Executes the given prepared statement with inputParams and returns the result.
+     * @param preparedStatement The prepared statement to execute.
+     * @param inputParams The parameter pack where each arg is a std::pair with the first element
+     * being parameter name and second element being parameter value.
+     * @return The result of the query.
+     * @note Any call that goes through executeWithParams acquires a lock in the end by calling
+     * executeLock(...).
+     */
     KUZU_API std::unique_ptr<QueryResult> executeWithParams(PreparedStatement* preparedStatement,
         std::unordered_map<std::string, std::shared_ptr<common::Value>>& inputParams);
-
+    /**
+     * @return All node table names in string format.
+     */
     KUZU_API std::string getNodeTableNames();
+    /**
+     * @return All rel table names in string format.
+     */
     KUZU_API std::string getRelTableNames();
+    /**
+     * @param nodeTableName The name of the node table.
+     * @return All property names of the given table.
+     */
     KUZU_API std::string getNodePropertyNames(const std::string& tableName);
+    /**
+     * @param relTableName The name of the rel table.
+     * @return All property names of the given table.
+     */
     KUZU_API std::string getRelPropertyNames(const std::string& relTableName);
 
 protected:

src/include/main/database.h

@@ -10,34 +10,80 @@
 namespace kuzu {
 namespace main {
 
+/**
+ * @brief Stores buffer pool size and max number of threads configurations.
+ */
 KUZU_API struct SystemConfig {
+    /**
+     * @brief Creates a SystemConfig object with default buffer pool size and max num of threads.
+     */
     explicit SystemConfig();
+    /**
+     * @brief Creates a SystemConfig object.
+     * @param bufferPoolSize Buffer pool size in bytes.
+     * @note defaultPageBufferPoolSize and largePageBufferPoolSize are calculated based on the
+     * DEFAULT_PAGES_BUFFER_RATIO and LARGE_PAGES_BUFFER_RATIO constants in StorageConfig.
+     */
     explicit SystemConfig(uint64_t bufferPoolSize);
 
     uint64_t defaultPageBufferPoolSize;
     uint64_t largePageBufferPoolSize;
     uint64_t maxNumThreads;
 };
 
+/**
+ * @brief Stores databasePath.
+ */
 KUZU_API struct DatabaseConfig {
+    /**
+     * @brief Creates a DatabaseConfig object.
+     * @param databasePath Path to store the database files.
+     */
     explicit DatabaseConfig(std::string databasePath);
 
     std::string databasePath;
 };
 
+/**
+ * @brief Database class is the main class of the KuzuDB. It manages all database configurations and
+ * files.
+ */
 class Database {
     friend class EmbeddedShell;
     friend class Connection;
     friend class JOConnection;
     friend class kuzu::testing::BaseGraphTest;
 
 public:
+    /**
+     * @brief Creates a database object with default buffer pool size and max num threads.
+     * @param databaseConfig Database configurations(database path).
+     */
     KUZU_API explicit Database(DatabaseConfig databaseConfig);
+    /**
+     * @brief Creates a database object.
+     * @param databaseConfig Database configurations(database path).
+     * @param systemConfig System configurations(buffer pool size and max num threads).
+     */
     KUZU_API Database(DatabaseConfig databaseConfig, SystemConfig systemConfig);
+    /**
+     * @brief Deconstructs the database object.
+     */
     KUZU_API ~Database();
 
+    /**
+     * @brief Sets the logging level of the database instance.
+     * @param loggingLevel New logging level. (Supported logging levels are: "info", "debug",
+     * "err").
+     */
     void setLoggingLevel(std::string loggingLevel);
 
+    /**
+     * @brief Resizes the buffer pool size of the database instance.
+     * @param newSize New buffer pool size in bytes.
+     * @throws BufferManagerException if the new size is smaller than the current buffer manager
+     * size.
+     */
     KUZU_API void resizeBufferManager(uint64_t newSize);
 
 private:

src/include/main/doc

@@ -0,0 +1,127 @@
+## class kuzu::main::DataTypeInfo
+
+
+
+---
+
+## class kuzu::main::QueryResult
+
+QueryResult stores the result of a query execution.  
+
+---
+
+```c++
+QueryResult (const PreparedSummary & preparedSummary)
+```
+Creates a QueryResult object. 
+
+**Parameters**
+- `preparedSummary` stores compiling time and query options. 
+
+---
+
+```c++
+std::vector<common::DataType> getColumnDataTypes ()
+```
+
+**Returns:**
+- dataType of each column in query result. 
+
+---
+
+```c++
+std::vector<std::string> getColumnNames ()
+```
+
+**Returns:**
+- name of each column in query result. 
+
+---
+
+```c++
+std::vector<std::unique_ptr<DataTypeInfo> > getColumnTypesInfo ()
+```
+
+**Returns:**
+- dataTypeInfo of each column. 
+
+---
+
+```c++
+std::string getErrorMessage ()
+```
+
+**Returns:**
+- error message of the query execution if the query fails. 
+
+---
+
+```c++
+std::shared_ptr<processor::FlatTuple> getNext ()
+```
+
+**Returns:**
+- next flat tuple in the query result. 
+
+---
+
+```c++
+size_t getNumColumns ()
+```
+
+**Returns:**
+- number of columns in query result. 
+
+---
+
+```c++
+uint64_t getNumTuples ()
+```
+
+**Returns:**
+- num of tuples in query result. 
+
+---
+
+```c++
+QuerySummary* getQuerySummary ()
+```
+
+**Returns:**
+- query summary which stores the execution time, compiling time, plan and query options. 
+
+---
+
+```c++
+bool hasNext ()
+```
+
+**Returns:**
+- whether there are more tuples to read. 
+
+---
+
+```c++
+bool isSuccess ()
+```
+
+**Returns:**
+- query is executed successfully or not. 
+
+---
+
+```c++
+void writeToCSV (const std::string & fileName, char delimiter = ',', char escapeCharacter = ''', char newline = 'n')
+```
+writes the query result to a csv file. 
+
+**Parameters**
+- `fileName` name of the csv file. 
+- `delimiter` delimiter of the csv file. 
+- `escapeCharacter` escape character of the csv file. 
+- `newline` newline character of the csv file. 
+
+---
+
+###### API documentation generated using [Doxygenmd](https://github.com/d99kris/doxygenmd)
+

src/include/main/prepared_statement.h

@@ -7,6 +7,10 @@
 namespace kuzu {
 namespace main {
 
+/**
+ * @brief A prepared statement is a parameterized query which can avoid planning the same query for
+ * repeated execution.
+ */
 class PreparedStatement {
     friend class Connection;
     friend class JOConnection;
@@ -15,10 +19,27 @@ class PreparedStatement {
     friend class kuzu::transaction::TinySnbCopyCSVTransactionTest;
 
 public:
+    /**
+     * @brief DDL and COPY_CSV statements are automatically wrapped in a transaction and committed.
+     * As such, they cannot be part of an active transaction.
+     * @return The prepared statement is allowed to be part of an active transaction.
+     */
     KUZU_API bool allowActiveTransaction() const;
+    /**
+     * @return The query is prepared successfully or not.
+     */
     KUZU_API bool isSuccess() const;
+    /**
+     * @return The error message if the query is not prepared successfully.
+     */
     KUZU_API std::string getErrorMessage() const;
+    /**
+     * @return The prepared statement is read-only or not.
+     */
     KUZU_API bool isReadOnly() const;
+    /**
+     * @return Expressions for generating query results.
+     */
     std::vector<std::shared_ptr<binder::Expression>> getExpressionsToCollect();
 
 private: