commit 112c0ce7b1ebb184888e0692fd868195df97fd34
parent a02d9f298d4ccf03e51a00404abd193dcb9f11d9
Author: Jacki <jacki@thejackimonster.de>
Date: Wed, 8 May 2024 16:27:25 +0200
Add doxygen comments for documentation of newer structs and functions
Signed-off-by: Jacki <jacki@thejackimonster.de>
Diffstat:
3 files changed, 153 insertions(+), 0 deletions(-)
diff --git a/src/internal/gnunet_chat_accounts.h b/src/internal/gnunet_chat_accounts.h
@@ -53,18 +53,58 @@ struct GNUNET_CHAT_InternalAccounts
struct GNUNET_CHAT_InternalAccounts *prev;
};
+/**
+ * Creates a new internal account resource to
+ * manage accounts for a given chat <i>handle</i>.
+ *
+ * The internal account gets appended to the
+ * list of accounts from the handle implicitly.
+ *
+ * An internal account might represent only an
+ * operation regarding a certain account while not
+ * representing the actual account. In most cases
+ * however this will be equivalent
+ * (for example iteration).
+ *
+ * @param[in,out] handle Chat handle
+ * @param[in,out] account Chat account or NULL
+ * @return New internal account resource
+ */
struct GNUNET_CHAT_InternalAccounts*
internal_accounts_create(struct GNUNET_CHAT_Handle *handle,
struct GNUNET_CHAT_Account *account);
+/**
+ * Destroys and frees an internal <i>accounts</i>
+ * resource while implicitly removing it from its
+ * chat handles list of accounts.
+ *
+ * @param[out] accounts Internal account resource
+ */
void
internal_accounts_destroy(struct GNUNET_CHAT_InternalAccounts *accounts);
+/**
+ * Initializes a given internal <i>accounts</i>
+ * resource with a selected account <i>method</i>
+ * to start further internal operations.
+ *
+ * @param[in,out] accounts Internal account resource
+ * @param[in] method Account method
+ * @param[in] identifier Account identifier or NULL
+ */
void
internal_accounts_start_method(struct GNUNET_CHAT_InternalAccounts *accounts,
enum GNUNET_CHAT_AccountMethod method,
const char *identifier);
+/**
+ * Resets a given internal <i>accounts</i>
+ * resource to a neutral method state and stops
+ * its current operation.
+ *
+ * @param[in,out] accounts Internal account resource
+ */
void
internal_accounts_stop_method(struct GNUNET_CHAT_InternalAccounts *accounts);
diff --git a/src/internal/gnunet_chat_attribute_process.h b/src/internal/gnunet_chat_attribute_process.h
@@ -57,30 +57,99 @@ struct GNUNET_CHAT_AttributeProcess
struct GNUNET_CHAT_AttributeProcess *prev;
};
+/**
+ * Creates a new attribute process resource to
+ * handle general attribute management using
+ * a given chat <i>handle</i>.
+ *
+ * The attribute process gets appended to the
+ * list of processes from the handle implicitly.
+ *
+ * @param[in,out] handle Chat handle
+ * @param[in] name Attribute name or NULL
+ * @return New attribute process
+ */
struct GNUNET_CHAT_AttributeProcess*
internal_attributes_create(struct GNUNET_CHAT_Handle *handle,
const char *name);
+/**
+ * Creates a new attribute process resource to
+ * handle attribute storage of an attribute with
+ * a specific <i>name</i> using a given chat
+ * <i>handle</i> and a relative datetime it
+ * <i>expires</i>.
+ *
+ * @see internal_attributes_create()
+ *
+ * @param[in,out] handle Chat handle
+ * @param[in] Attribute name
+ * @param[in] expires Relative time for expiration
+ * @return New attribute storage process
+ */
struct GNUNET_CHAT_AttributeProcess*
internal_attributes_create_store(struct GNUNET_CHAT_Handle *handle,
const char *name,
struct GNUNET_TIME_Relative expires);
+/**
+ * Creates a new attribute process resource to
+ * handle attribute sharing of an attribute with
+ * a specific <i>name</i> for a certain chat
+ * <i>contact</i> using a given chat <i>handle</i>.
+ *
+ * @see internal_attributes_create()
+ *
+ * @param[in,out] handle Chat handle
+ * @param[in,out] contact Chat contact
+ * @param[in] Attribute name
+ * @return New attribute sharing process
+ */
struct GNUNET_CHAT_AttributeProcess*
internal_attributes_create_share(struct GNUNET_CHAT_Handle *handle,
struct GNUNET_CHAT_Contact *contact,
const char *name);
+/**
+ * Creates a new attribute process resource to
+ * request attributes from a specific chat
+ * <i>account</i> using a given chat <i>handle</i>.
+ *
+ * @see internal_attributes_create()
+ *
+ * @param[in,out] handle Chat handle
+ * @param[in] account Chat account
+ * @return New attribute request process
+ */
struct GNUNET_CHAT_AttributeProcess*
internal_attributes_create_request(struct GNUNET_CHAT_Handle *handle,
const struct GNUNET_CHAT_Account *account);
+/**
+ * Destroys and frees a given <i>attributes</i>
+ * process resource. This will implicitly remove
+ * it from its chat handles list of processes.
+ *
+ * @param[out] attributes Attribute process
+ */
void
internal_attributes_destroy(struct GNUNET_CHAT_AttributeProcess *attributes);
+/**
+ * Continues the iteration of a given <i>attributes</i>
+ * process resource to its next step.
+ *
+ * @param[in,out] attributes Attribute process
+ */
void
internal_attributes_next_iter(struct GNUNET_CHAT_AttributeProcess *attributes);
+/**
+ * Stops the iteration of a given <i>attributes</i>
+ * process resource.
+ *
+ * @param[in,out] attributes Attribute process
+ */
void
internal_attributes_stop_iter(struct GNUNET_CHAT_AttributeProcess *attributes);
diff --git a/src/internal/gnunet_chat_ticket_process.h b/src/internal/gnunet_chat_ticket_process.h
@@ -50,21 +50,65 @@ struct GNUNET_CHAT_TicketProcess
struct GNUNET_CHAT_TicketProcess *prev;
};
+/**
+ * Creates a new ticket process resource to
+ * handle general ticket management from
+ * a specific char <i>contact</i> using
+ * a given chat <i>handle</i>.
+ *
+ * The ticket process gets appended to the
+ * list of processes from the handle implicitly.
+ *
+ * @param[in,out] handle Chat handle
+ * @param[in,out] contact Chat contact
+ * @param[in] name Attribute name or NULL
+ * @return New ticket process
+ */
struct GNUNET_CHAT_TicketProcess*
internal_tickets_create(struct GNUNET_CHAT_Handle *handle,
struct GNUNET_CHAT_Contact *contact,
const char *name);
+/**
+ * Creates a new copy of a given <i>tickets</i>
+ * process with additional information about a
+ * valid reclaim <i>ticket</i>.
+ *
+ * @see internal_tickets_create()
+ *
+ * @param[in] tickets Original ticket process
+ * @param[in] ticket Reclaim ticket or NULL
+ * @return New ticket process
+ */
struct GNUNET_CHAT_TicketProcess*
internal_tickets_copy(const struct GNUNET_CHAT_TicketProcess* tickets,
const struct GNUNET_RECLAIM_Ticket *ticket);
+/**
+ * Destroys and frees a given <i>tickets</i>
+ * process resource. This will implicitly remove
+ * it from its chat handles list of processes.
+ *
+ * @param[out] tickets Ticket process
+ */
void
internal_tickets_destroy(struct GNUNET_CHAT_TicketProcess *tickets);
+/**
+ * Continues the iteration of a given <i>tickets</i>
+ * process resource to its next step.
+ *
+ * @param[in,out] tickets Ticket process
+ */
void
internal_tickets_next_iter(struct GNUNET_CHAT_TicketProcess *tickets);
+/**
+ * Stops the iteration of a given <i>tickets</i>
+ * process resource.
+ *
+ * @param[in,out] tickets Ticket process
+ */
void
internal_tickets_stop_iter(struct GNUNET_CHAT_TicketProcess *tickets);
