libqaeda

commit 4862662dacde684bfbeade3129b8a0b29fd77e20
parent 2c018a4667e129b9343f78279b0d41d13f85d346
Author: lash <dev@holbrook.no>
Date:   Sun,  2 Mar 2025 22:15:37 +0000

Add documentation

Diffstat:
M
src/lq/cert.h
 | 
2
++
M
src/lq/io.h
 | 
6
++++++
M
src/lq/msg.h
 | 
2
++
M
src/lq/store.h
 | 
22
++++++++++++++++++++++

4 files changed, 32 insertions(+), 0 deletions(-)
diff --git a/src/lq/cert.h b/src/lq/cert.h
@@ -89,6 +89,7 @@ int lq_certificate_sign(LQCert *cert, LQPrivKey *pk);
  * @param[in] Certificate to serialize
  * @param[out] Buffer to write data to.
  * @param[out] Value behind pointer must contain the capacity of the output buffer. Will be overwritten with the actual number of bytes written.
+ * @param[in] Store implementations to use for storing serialized certificate and message data.
  * @return ERR_OK if serialization is successful, or:
  * 	* ERR_INIT if the serialization object couldn't be instantiated.
  * 	* ERR_OVERFLOW if output exceeded the available space in output buffer.
@@ -102,6 +103,7 @@ int lq_certificate_serialize(LQCert *cert, char *out, size_t *out_len, LQResolve
  * @param[out] Pointer to instantiated certificate. It is the caller's responsibility to free the certificate object.
  * @param[in] Serialized data.
  * @param[in] Length of serialized data.
+ * @param[in] Store implementations to use for resolving content key from deserialized message and certificate data.
  * @return ERR_OK if deserialization is successful, or:
  * 	* ERR_INIT if the serialization object couldn't be instantiated.
  * 	* ERR_READ if deserialization of an element failed.
diff --git a/src/lq/io.h b/src/lq/io.h
@@ -1,6 +1,12 @@
 #ifndef LIBQAEDA_IO_H_
 #define LIBQAEDA_IO_H_
 
+/***
+ * @brief Create temporary directory using template.
+ *
+ * @param[in] Directory path template
+ * @return Pointer to valid path string. NULL if directory could not be created.
+ */
 char* mktempdir(char *s);
 
 #endif // LIBQAEDA_IO_H_
diff --git a/src/lq/msg.h b/src/lq/msg.h
@@ -63,6 +63,7 @@ LQSig* lq_msg_sign_extra(LQMsg *msg, LQPrivKey *pk, const char *salt, const char
  * @param[in] Message to serialize.
  * @param[out] Output buffer.
  * @param[out] Value behind pointer must contain the capacity of output buffer. Will be overwritten with the actual number of bytes written.
+ * @param[in] Store implementations to use for storing serialized message data.
  * @return ERR_OK if serialization is successful, or:
  * 	* ERR_INIT if the serialization object couldn't be instantiated.
  * 	* ERR_OVERFLOW if output exceeded the available space in output buffer.
@@ -76,6 +77,7 @@ int lq_msg_serialize(LQMsg *msg, char *out, size_t *out_len, LQResolve *resolve)
  * @param[out] Pointer to instantiated message. It is the caller's responsibility to free the message object.
  * @param[in] Serialized data.
  * @param[in] Length of serialized data.
+ * @param[in] Store implementations to use for resolving content key from deserialized message data.
  * @return ERR_OK if deserialization is successful, or:
  * 	* ERR_INIT if the serialization object couldn't be instantiated.
  * 	* ERR_READ if deserialization of an element failed.
diff --git a/src/lq/store.h b/src/lq/store.h
@@ -3,6 +3,7 @@
 
 #include <stddef.h>
 
+/// Payload type hint to control how and what a store implementation executes persistence.
 enum payload_e {
 	LQ_CONTENT_RAW,
 	LQ_CONTENT_MSG,
@@ -10,6 +11,18 @@ enum payload_e {
 	LQ_CONTENT_KEY,
 };
 
+/***
+ * @struct LQStore
+ * @brief Store interface, implemented by all IO backends; network, db, filesystem and memory.
+ * @var LQStore::store_typ
+ * Store type identifier, used for implementation methods to ensure that the correct version of a store structure has been passed.
+ * @var LQStore::userdata
+ * Implementation specific data required by the specific store.
+ * @var LQStore::get
+ * Interface for retrieving data corresponding to a key.
+ * @var LQStore::put
+ * Interface for storing data corresponding to a key.
+ */
 typedef struct lq_store_t LQStore;
 struct lq_store_t {
 	int store_typ;
@@ -19,6 +32,15 @@ struct lq_store_t {
 };
 
 
+/***
+ * @struct LQResolve
+ * @brief A linked list of stores that should be used for a specific context or action.
+ * @var LQResolve::store
+ * Store interface implementation.
+ * @var LQResolve::next
+ * Provides access to next store implementation to store to or retrieve from. Setting to NULL stops any further action.
+ * @todo Add a list of content types, for while store action will be taken and otherwise ignored.
+ */
 typedef struct lq_resolve_t LQResolve;
 struct lq_resolve_t {
 	LQStore *store;