From 67957ab4f164a9853283bcec7bd593c651784126 Mon Sep 17 00:00:00 2001
From: auxten <auxtenwpc@gmail.com>
Date: Wed, 8 Jan 2025 21:55:26 +0800
Subject: [PATCH] Add docs for chdb connection related C API

---
 programs/local/chdb.h | 40 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 36 insertions(+), 4 deletions(-)

diff --git a/programs/local/chdb.h b/programs/local/chdb.h
index ae8f354ac69..1188128b0f1 100644
--- a/programs/local/chdb.h
+++ b/programs/local/chdb.h
@@ -66,7 +66,7 @@ struct query_queue
 {
     std::mutex mutex;
     std::condition_variable query_cv; // For query submission
-    std::condition_variable result_cv;
+    std::condition_variable result_cv; // For query result retrieval
     query_request current_query;
     local_result_v2 * current_result = nullptr;
     bool has_query = false;
@@ -75,15 +75,47 @@ struct query_queue
 };
 #endif
 
+/**
+ * Connection structure for chDB
+ * Contains server instance, connection state, and query processing queue
+ */
 struct chdb_conn
 {
-    void * server; // LocalServer * server;
-    bool connected;
-    void * queue; // query_queue*
+    void * server; /* ClickHouse LocalServer instance */
+    bool connected; /* Connection state flag */
+    void * queue; /* Query processing queue */
 };
 
+/**
+ * Creates a new chDB connection.
+ * Only one active connection is allowed per process.
+ * Creating a new connection with different path requires closing existing connection.
+ * 
+ * @param argc Number of command-line arguments
+ * @param argv Command-line arguments array (--path=<db_path> to specify database location)
+ * @return Pointer to connection pointer, or NULL on failure
+ * @note Default path is ":memory:" if not specified
+ */
 CHDB_EXPORT struct chdb_conn ** connect_chdb(int argc, char ** argv);
+
+/**
+ * Closes an existing chDB connection and cleans up resources.
+ * Thread-safe function that handles connection shutdown and cleanup.
+ * 
+ * @param conn Pointer to connection pointer to close
+ */
 CHDB_EXPORT void close_conn(struct chdb_conn ** conn);
+
+/**
+ * Executes a query on the given connection.
+ * Thread-safe function that handles query execution in a separate thread.
+ * 
+ * @param conn Connection to execute query on
+ * @param query SQL query string to execute
+ * @param format Output format string (e.g., "CSV", default format)
+ * @return Query result structure containing output or error message
+ * @note Returns error result if connection is invalid or closed
+ */
 CHDB_EXPORT struct local_result_v2 * query_conn(struct chdb_conn * conn, const char * query, const char * format);
 
 #ifdef __cplusplus