docs(libacron): add library docs

Signed-off-by: Trumeet <yuuta@yuuta.moe>

7 files changed, 83 insertions, 2 deletions

diff --git a/client/libacron/include/ids.h b/client/libacron/include/ids.h
index 86fde47..80e7448 100644
--- a/client/libacron/include/ids.h
+++ b/client/libacron/include/ids.h
@@ -21,6 +21,11 @@ typedef struct ac_obj {
     uint8_t type;
 } ac_obj_t;
 
+/**
+ * Free the object.
+ * @param obj Object to free. Must be a valid object.
+ * @return AC_E_OK or an error code. When succeeds, obj is freed and no longer valid.
+ */
 int ac_object_free(ac_obj_t *obj);
 
 #endif /* LIBAC_IDS_H */
diff --git a/client/libacron/include/libac.h b/client/libacron/include/libac.h
index 80734dc..542adcb 100644
--- a/client/libacron/include/libac.h
+++ b/client/libacron/include/libac.h
@@ -21,13 +21,13 @@ typedef struct libac_config {
 
 /**
  * Initialize libac for the calling thread.
- * @return 0 on success.
+ * @return AC_E_OK on success.
  */
 int ac_init(const libac_config_t *config);
 
 /**
  * Destroy libac configuration for the calling thread.
- * @return 0 on success.
+ * @return AC_E_OK on success.
  */
 int ac_free(void);
 
diff --git a/client/libacron/include/net.h b/client/libacron/include/net.h
index 5b10470..8fb33f8 100644
--- a/client/libacron/include/net.h
+++ b/client/libacron/include/net.h
@@ -20,10 +20,29 @@ typedef struct ac_connection_parameters {
     char *url;
 } ac_connection_parameters_t;
 
+/**
+ * Connect to the server.
+ * @param parameters Connection parameters. Untouched.
+ * @param out Output connection reference if succeeds. Not-NULL.
+ * @return AC_E_OK or an error code. When failed, *out will be untouched.
+ * MT-Safe
+ */
 int ac_connect(ac_connection_parameters_t parameters, void **out);
 
+/**
+ * Disconnect the connection.
+ * @param connection A non-NULL and connected connection passed as-is from ac_connect.
+ * @return AC_E_OK or an error code. When failed, connection is undefined. When succeeds, connection is freed and invalid.
+ * MT-Unsafe
+ */
 int ac_disconnect(void *connection);
 
+/**
+ * Blocks the current thread until a new response or event arrives.
+ * @param connection A non-NULL and connected connection passed as-is from ac_connect.
+ * @param response Output response of either an event or a response. May be NULL even if it succeeds.
+ * @return AC_E_OK or an error code. When failed, *response is NULL.
+ */
 int ac_receive(void *connection, ac_obj_t **response);
 
 #endif /* LIBAC_NET_H */
diff --git a/client/libacron/include/requests.h b/client/libacron/include/requests.h
index 40742e0..590bb2e 100644
--- a/client/libacron/include/requests.h
+++ b/client/libacron/include/requests.h
@@ -66,6 +66,14 @@ typedef struct ac_request_set_config {
     ac_config_t config;
 } ac_request_set_config_t;
 
+/**
+ * Send a request to the connection. If this function succeeds, ac_receive() will return a response
+ * with the same ID later.
+ * @param connection Must be a non-NULL and connected connection, or it will return AC_E_INVALID_REQUEST.
+ * @param request A valid ac_request_t. It will left untouched.
+ * @return AC_E_OK or an error code.
+ * MT-Unsafe: Must be called on the same thread calling ac_receive().
+ */
 int ac_request(void *connection, const ac_request_t *request);
 
 #endif /* LIBAC_REQUESTS_H */
diff --git a/client/libacron/private/connection.h b/client/libacron/private/connection.h
index 1c1567f..ad65b11 100644
--- a/client/libacron/private/connection.h
+++ b/client/libacron/private/connection.h
@@ -9,12 +9,18 @@
 #include "libac.h"
 #include <stdbool.h>
 
+/**
+ * Used to transfer deserialization result from receive handler to ac_receive().
+ */
 struct ac_result {
     bool has_result;
     int res;
     ac_obj_t *obj;
 };
 
+/**
+ * Internal representation of void *connection.
+ */
 struct ac_connection {
     ac_connection_parameters_t parameters;
     struct wic_inst inst;
diff --git a/client/libacron/private/helpers.h b/client/libacron/private/helpers.h
index 20dfeec..f1635a6 100644
--- a/client/libacron/private/helpers.h
+++ b/client/libacron/private/helpers.h
@@ -9,14 +9,37 @@
 
 #define SALLOC(s, out) alloc(NULL, 1, sizeof(s), true, (void **) out)
 
+/**
+ * Allocate or reallocate a range of memory on heap.
+ * @param existing The existing range to extend. NULL-able.
+ * @param count The number of bytes. Final size = count * bytes.
+ * @param bytes The size. Final size = count * bytes.
+ * @param zero_out Whether to zero out the newly-allocated memory. Ignored when existing != NULL.
+ * @param out Output memory range. Not NULL if the return value is AC_E_OK.
+ * @return AC_E_OK or an error code. When failed, *out is untouched.
+ * MT-Safe
+ */
 int alloc(void *existing,
             unsigned int count,
             unsigned int bytes,
             bool zero_out,
             void **out);
 
+/**
+ * Duplicate a string.
+ * @param str String to duplicate.
+ * @param out Output string. Not NULL if the return value is AC_E_OK.
+ * @return AC_E_OK or an error code. When failed, *out is untouched.
+ * MT-Safe
+ */
 int strdup2(const char *str, char **out);
 
+/**
+ * Cross-platform thread-safe wrapper of strerror(3).
+ * @param errnum errno
+ * @return Always non-NULL error message.
+ * MT-Safe
+ */
 char *strerror2(int errnum);
 
 #endif /* LIBAC_HELPERS_H */
diff --git a/client/libacron/private/serializer.h b/client/libacron/private/serializer.h
index 1b9a38b..cbc9557 100644
--- a/client/libacron/private/serializer.h
+++ b/client/libacron/private/serializer.h
@@ -9,10 +9,30 @@
  * Should not conflict with other error codes. */
 #define AC_E_SERIALIZER_CONTINUE    -1
 
+/**
+ * Deserialize an event or a response into ac_obj_t.
+ * @param string The partial or complete response.
+ * @param len The length to the string, excluding tailing NULL.
+ * @param out The final object. Not NULL if the return value is AC_E_OK.
+ * @return AC_E_OK or an error code. When failed, the *out is untouched.
+ * MT-Safe config
+ */
 int deserialize(const char *string, unsigned int len, ac_obj_t **out);
 
+/**
+ * Force a deserializer reset.
+ * @return AC_E_OK or an error code.
+ * MT-Safe
+ */
 int serializer_finalize(void);
 
+/**
+ * Serialize a request to a JSON object.
+ * @param req The request. Must be a valid ac_request.
+ * @param out The output json_object. Will not be NULL if the return value is AC_E_OK.
+ * @return AC_E_OK or an error code. When failed, the *out is untouched.
+ * MT-Safe
+ */
 int serialize_request(const ac_request_t *req, json_object **out);
 
 #endif /* LIBAC_SERIALIZER_H */