Merge pull request #35 from SpringQL/docs/header-file-doc

docs: update doc comments on functions and structures

Author: laysakura

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "springql-client-c"
-version = "0.9.0"
+version = "0.9.0+2"
 
 authors = ["Sho Nakatani <lay.sakura@gmail.com>"]
 license = "MIT OR Apache-2.0"

springql.h

@@ -7,8 +7,6 @@
 
 /**
  * Errno (error number) to be returned erroneous functions.
- *
- * See springql_core::api::error::SpringError for details of each error reason.
  */
 typedef enum SpringErrno {
   Ok = 0,
@@ -37,210 +35,253 @@ typedef enum SpringErrno {
   CNull = -127,
 } SpringErrno;
 
+/**
+ * Configuration.
+ */
 typedef void *SpringConfig;
 
+/**
+ * Pipeline (dataflow definition) in SpringQL.
+ */
 typedef void *SpringPipeline;
 
+/**
+ * Row object from an in memory queue.
+ */
 typedef void *SpringRow;
 
 /**
- * See: springql_core::api::spring_config_default
+ * Returns default configuration.
  *
  * Returned value is not modifiable (it is just a void pointer).
  * If you would like to change the default configuration, use `spring_config_toml()` instead.
  */
 SpringConfig *spring_config_default(void);
 
 /**
- * See: springql_core::api::spring_config_default
+ * Configuration by TOML format string.
  *
  * Returned value is not modifiable (it is just a void pointer).
- * If you would like to change the default configuration, use `spring_config_toml()` instead.
  *
- * # Safety
+ * # Parameters
  *
- * This function is unsafe because it uses raw pointer.
+ * - `overwrite_config_toml`: TOML format configuration to overwrite default.
+ *   See https://springql.github.io/deployment/configuration for TOML format and configuration values.
+ *
+ * # Panics
+ *
+ * Currently, the process aborts when:
+ *
+ * - `overwrite_config_toml` includes invalid key and/or value.
+ * - `overwrite_config_toml` is not valid as TOML.
  */
 SpringConfig *spring_config_toml(const char *overwrite_config_toml);
 
 /**
- * # Returns
- *
- * - `0`: if there are no recent errors.
- * - `< 0`: SpringErrno
+ * Frees heap occupied by a `SpringConfig`.
  *
- * # Safety
+ * # Returns
  *
- * This function is unsafe because it uses raw pointer.
+ * - `Ok`: on success.
+ * - `CNull`: `config` is a NULL pointer.
  */
 enum SpringErrno spring_config_close(SpringConfig *config);
 
 /**
- * See: springql_core::api::spring_open
+ * Creates and open an in-process stream pipeline.
  *
  * # Returns
  *
  * - non-NULL: on success
  * - NULL: on failure. Check spring_last_err() for details.
  *
- * # Safety
+ * # Errors
  *
- * This function is unsafe because it uses raw pointer.
+ * No errors are expected currently.
  */
 SpringPipeline *spring_open(const SpringConfig *config);
 
 /**
- * # Returns
- *
- * - `0`: if there are no recent errors.
- * - `< 0`: SpringErrno
+ * Frees heap occupied by a `SpringPipeline`.
  *
- * # Safety
+ * # Returns
  *
- * This function is unsafe because it uses raw pointer.
+ * - `Ok`: on success.
+ * - `CNull`: `pipeline` is a NULL pointer.
  */
 enum SpringErrno spring_close(SpringPipeline *pipeline);
 
 /**
- * See: springql_core::api::spring_command
+ * Execute commands (DDL) to modify the pipeline.
  *
  * # Returns
  *
- * - `0`: if there are no recent errors.
- * - `< 0`: SpringErrno
- *
- * # Safety
- *
- * This function is unsafe because it uses raw pointer.
+ * - `Ok`: on success.
+ * - `Sql`:
+ *   - Invalid SQL syntax.
+ *   - Refers to undefined objects (streams, pumps, etc)
+ *   - Other semantic errors.
+ * - `InvalidOption`:
+ *   - `OPTIONS` in `CREATE` statement includes invalid key or value.
  */
 enum SpringErrno spring_command(const SpringPipeline *pipeline, const char *sql);
 
 /**
- * See: springql_core::api::spring_pop
+ * Pop a row from an in memory queue. This is a blocking function.
+ *
+ * Do not call this function from threads.
+ * If you need to pop from multiple in-memory queues using threads, use `spring_pop_non_blocking()`.
+ * See: https://github.com/SpringQL/SpringQL/issues/125
  *
  * # Returns
  *
  * - non-NULL: on success
  * - NULL: on failure. Check spring_last_err() for details.
  *
- * # Safety
+ * # Errors
  *
- * This function is unsafe because it uses raw pointer.
+ * - `Unavailable`: queue named `queue` does not exist.
  */
 SpringRow *spring_pop(const SpringPipeline *pipeline, const char *queue);
 
 /**
- * See: springql_core::api::spring_pop_non_blocking
+ * Pop a row from an in memory queue. This is a non-blocking function.
  *
  * # Returns
  *
  * - non-NULL: Successfully get a row.
  * - NULL: Error occurred if `is_err` is true (check spring_last_err() for details). Otherwise, any row is not in the queue.
  *
- * # Safety
+ * # Errors
  *
- * This function is unsafe because it uses raw pointer.
+ * - `Unavailable`: queue named `queue` does not exist.
  */
 SpringRow *spring_pop_non_blocking(const SpringPipeline *pipeline,
                                    const char *queue,
                                    bool *is_err);
 
 /**
- * # Returns
- *
- * - `0`: if there are no recent errors.
- * - `< 0`: SpringErrno
+ * Frees heap occupied by a `SpringRow`.
  *
- * # Safety
+ * # Returns
  *
- * This function is unsafe because it uses raw pointer.
+ * - `Ok`: on success.
+ * - `CNull`: `pipeline` is a NULL pointer.
  */
 enum SpringErrno spring_row_close(SpringRow *row);
 
 /**
- * See: springql_core::api::spring_column_i16
+ * Get a 2-byte integer column.
  *
- * # Returns
+ * # Parameters
  *
- * - `0`: if there are no recent errors.
- * - `< 0`: SpringErrno
+ * - `row`: A `SpringRow` pointer to get a column value from.
+ * - `i_col`: The column index to get a value from.
+ * - `out`: A pointer to a buffer to store the column value.
  *
- * # Safety
+ * # Returns
  *
- * This function is unsafe because it uses raw pointer.
+ * - `Ok`: On success.
+ * - `Unavailable`:
+ *   - Column pointed by `i_col` is already fetched.
+ *   - `i_col` is out of range.
+ * - `CNull`: Column value is NULL.
  */
 enum SpringErrno spring_column_short(const SpringRow *row, uint16_t i_col, short *out);
 
 /**
- * See: springql_core::api::spring_column_i32
+ * Get a 4-byte integer column.
  *
- * # Returns
+ * # Parameters
  *
- * - `0`: if there are no recent errors.
- * - `< 0`: SpringErrno
+ * - `row`: A `SpringRow` pointer to get a column value from.
+ * - `i_col`: The column index to get a value from.
+ * - `out`: A pointer to a buffer to store the column value.
  *
- * # Safety
+ * # Returns
  *
- * This function is unsafe because it uses raw pointer.
+ * - `Ok`: On success.
+ * - `Unavailable`:
+ *   - Column pointed by `i_col` is already fetched.
+ *   - `i_col` is out of range.
+ * - `CNull`: Column value is NULL.
  */
 enum SpringErrno spring_column_int(const SpringRow *row, uint16_t i_col, int *out);
 
 /**
- * See: springql_core::api::spring_column_i64
+ * Get an 8-byte integer column.
  *
- * # Returns
+ * # Parameters
  *
- * - `0`: if there are no recent errors.
- * - `< 0`: SpringErrno
+ * - `row`: A `SpringRow` pointer to get a column value from.
+ * - `i_col`: The column index to get a value from.
+ * - `out`: A pointer to a buffer to store the column value.
  *
- * # Safety
+ * # Returns
  *
- * This function is unsafe because it uses raw pointer.
+ * - `Ok`: On success.
+ * - `Unavailable`:
+ *   - Column pointed by `i_col` is already fetched.
+ *   - `i_col` is out of range.
+ * - `CNull`: Column value is NULL.
  */
 enum SpringErrno spring_column_long(const SpringRow *row, uint16_t i_col, long *out);
 
 /**
- * See: springql_core::api::spring_column_text
+ * Get a text column.
  *
- * This returns UTF-8 string into `out`.
+ * # Parameters
  *
- * # Returns
+ * - `row`: A `SpringRow` pointer to get a column value from.
+ * - `i_col`: The column index to get a value from.
+ * - `out`: A pointer to a buffer to store the column value.
+ * - `out_len`: The length of the buffer pointed by `out`.
  *
- * - `0`: if there are no recent errors.
- * - `> 0`: the length of the recent error message.
- * - `< 0`: SpringErrno
- *
- * # Safety
+ * # Returns
  *
- * This function is unsafe because it uses raw pointer.
+ * - `> 0`: Length of the text.
+ * - `Unavailable`:
+ *   - Column pointed by `i_col` is already fetched.
+ *   - `i_col` is out of range.
+ * - `CNull`: Column value is NULL.
  */
 int spring_column_text(const SpringRow *row, uint16_t i_col, char *out, int out_len);
 
 /**
- * See: springql_core::api::spring_column_bool
+ * Get a bool column.
  *
- * # Returns
+ * # Parameters
  *
- * - `0`: if there are no recent errors.
- * - `< 0`: SpringErrno
+ * - `row`: A `SpringRow` pointer to get a column value from.
+ * - `i_col`: The column index to get a value from.
+ * - `out`: A pointer to a buffer to store the column value.
  *
- * # Safety
+ * # Returns
  *
- * This function is unsafe because it uses raw pointer.
+ * - `Ok`: On success.
+ * - `Unavailable`:
+ *   - Column pointed by `i_col` is already fetched.
+ *   - `i_col` is out of range.
+ * - `CNull`: Column value is NULL.
  */
 enum SpringErrno spring_column_bool(const SpringRow *row, uint16_t i_col, bool *out);
 
 /**
- * See: springql_core::api::spring_column_f32
+ * Get a 4-byte floating point column.
  *
- * # Returns
+ * # Parameters
  *
- * - `0`: if there are no recent errors.
- * - `< 0`: SpringErrno
+ * - `row`: A `SpringRow` pointer to get a column value from.
+ * - `i_col`: The column index to get a value from.
+ * - `out`: A pointer to a buffer to store the column value.
  *
- * # Safety
+ * # Returns
  *
- * This function is unsafe because it uses raw pointer.
+ * - `Ok`: On success.
+ * - `Unavailable`:
+ *   - Column pointed by `i_col` is already fetched.
+ *   - `i_col` is out of range.
+ * - `CNull`: Column value is NULL.
  */
 enum SpringErrno spring_column_float(const SpringRow *row, uint16_t i_col, float *out);
 
@@ -262,10 +303,6 @@ enum SpringErrno spring_column_float(const SpringRow *row, uint16_t i_col, float
  * - `0`: if there are no recent errors.
  * - `> 0`: the length of the recent error message.
  * - `< 0`: SpringErrno
- *
- * # Safety
- *
- * This function is unsafe because it writes into a caller-provided buffer.
  */
 int spring_last_err(enum SpringErrno *errno,
                     char *errmsg,

src/cstr.rs

@@ -11,7 +11,7 @@ use crate::spring_errno::SpringErrno;
 
 /// # Returns
 ///
-/// - `> 0`: the length of the recent error message.
+/// - `> 0`: the length of `src`.
 /// - `< 0`: SpringErrno
 pub(super) fn strcpy(src: &str, dest_buf: *mut c_char, dest_len: c_int) -> c_int {
     if src.len() >= dest_len as usize {