Added doxygen comments to some headers

Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>

7 files changed, 244 insertions, 0 deletions

diff --git a/src/application.h b/src/application.h
index 2c0972b..ab082a0 100644
--- a/src/application.h
+++ b/src/application.h
@@ -134,15 +134,38 @@ typedef struct MESSENGER_Application
   } settings;
 } MESSENGER_Application;
 
+/**
+ * Initializes the messenger application with
+ * startup arguments.
+ *
+ * @param app Messenger application
+ * @param argc Amount of arguments
+ * @param argv Arguments
+ */
 void
 application_init(MESSENGER_Application *app,
                  int argc,
                  char **argv);
 
+/**
+ * Returns the path from resources of the
+ * messenger application relative to its storage.
+ *
+ * @param app Messenger application
+ * @param path Path
+ * @return Resource path
+ */
 const gchar*
 application_get_resource_path(MESSENGER_Application *app,
                               const char *path);
 
+/**
+ * Runs the messenger application starting the
+ * second thread and waiting for the application
+ * to finish.
+ *
+ * @param app Messenger application
+ */
 void
 application_run(MESSENGER_Application *app);
 
@@ -156,20 +179,49 @@ typedef void (*MESSENGER_ApplicationMessageEvent) (
     const struct GNUNET_CHAT_Message *msg
 );
 
+/**
+ * Calls a given event with the messenger application
+ * asyncronously but explicitly synchronized via mutex.
+ *
+ * @param app Messenger application
+ * @param event Event
+ */
 void
 application_call_event(MESSENGER_Application *app,
                        MESSENGER_ApplicationEvent event);
 
+/**
+ * Calls a given message event with the messenger
+ * application asyncronously but explicitly synchronized
+ * via mutex.
+ *
+ * @param app Messenger application
+ * @param event Message event
+ * @param context Chat context
+ * @param message Message
+ */
 void
 application_call_message_event(MESSENGER_Application *app,
                                MESSENGER_ApplicationMessageEvent event,
                                struct GNUNET_CHAT_Context *context,
                                const struct GNUNET_CHAT_Message *message);
 
+/**
+ * Signals the second thread to exit the application.
+ *
+ * @param app Messenger application
+ * @param signal Exit signal
+ */
 void
 application_exit(MESSENGER_Application *app,
                  MESSENGER_ApplicationSignal signal);
 
+/**
+ * Returns the exit status of the messenger application.
+ *
+ * @param app Messenger application
+ * @return Exit status
+ */
 int
 application_status(MESSENGER_Application *app);
 
diff --git a/src/chat/messenger.h b/src/chat/messenger.h
index bc07119..4cceec7 100644
--- a/src/chat/messenger.h
+++ b/src/chat/messenger.h
@@ -39,6 +39,15 @@ typedef struct CHAT_MESSENGER_Handle
   struct GNUNET_SCHEDULER_Task *idle;
 } CHAT_MESSENGER_Handle;
 
+/**
+ * Startup event of the GNUnet scheduler thread to
+ * handle the messenger application startup.
+ *
+ * @param cls Closure
+ * @param args Arguments
+ * @param cfgfile Configuration file path
+ * @param cfg Configuration
+ */
 void
 chat_messenger_run(void *cls,
                    char *const *args,
diff --git a/src/contact.h b/src/contact.h
index 8a6dd4c..61d41e7 100644
--- a/src/contact.h
+++ b/src/contact.h
@@ -35,27 +35,73 @@ typedef struct MESSENGER_ContactInfo
   GList *name_avatars;
 } MESSENGER_ContactInfo;
 
+/**
+ * Creates a contact information struct to potentially
+ * update all GUI appearances of a specific contact at
+ * once.
+ *
+ * @param contact Chat contact
+ */
 void
 contact_create_info(struct GNUNET_CHAT_Contact *contact);
 
+/**
+ * Destroys and frees resources allocated for a given
+ * contact information struct.
+ *
+ * @param contact Chat contact
+ */
 void
 contact_destroy_info(struct GNUNET_CHAT_Contact *contact);
 
+/**
+ * Sets the latest join/leave UI message handle so that
+ * the application can check whether a contact is available.
+ *
+ * @param contact Chat contact
+ * @param message Pointer to UI message handle
+ */
 void
 contact_set_last_message_to_info(const struct GNUNET_CHAT_Contact *contact,
                                  void *message);
 
+/**
+ * Returns the latest join/leave UI message handle of
+ * a specific contact.
+ *
+ * @param contact Chat contact
+ */
 void*
 contact_get_last_message_from_info(const struct GNUNET_CHAT_Contact *contact);
 
+/**
+ * Adds a GtkLabel to the list of labels
+ * which get updated by state changes.
+ *
+ * @param contact Chat contact
+ * @param label Label
+ */
 void
 contact_add_name_label_to_info(const struct GNUNET_CHAT_Contact *contact,
                                GtkLabel *label);
 
+/**
+ * Adds a HdyAvatar to the list of avatars
+ * which get updated by state changes.
+ *
+ * @param contact Chat contact
+ * @param avatar Avatar
+ */
 void
 contact_add_name_avatar_to_info(const struct GNUNET_CHAT_Contact *contact,
                                 HdyAvatar *avatar);
 
+/**
+ * Updates the connected UI elements for a given
+ * contact depending on the current state.
+ *
+ * @param contact Chat contact
+ */
 void
 contact_update_info(const struct GNUNET_CHAT_Contact *contact);
 
diff --git a/src/event.h b/src/event.h
index 505309c..d89e453 100644
--- a/src/event.h
+++ b/src/event.h
@@ -27,42 +27,114 @@
 
 #include "application.h"
 
+/**
+ * Event for the UI to be called whenever the application
+ * causes any issue in back-end throwing a warning. This
+ * might be specific to a given context or none if its
+ * a general warning.
+ *
+ * @param app Messenger application
+ * @param context Chat context or NULL
+ * @param msg Warning message
+ */
 void
 event_handle_warning(MESSENGER_Application *app,
                      struct GNUNET_CHAT_Context *context,
                      const struct GNUNET_CHAT_Message *msg);
 
+/**
+ * Event for the UI to be called whenever the accounts
+ * might add or remove an account from their list.
+ *
+ * @param app Messenger application
+ */
 void
 event_refresh_accounts(MESSENGER_Application *app);
 
+/**
+ * Event for the UI to be called whenever the user
+ * updates their information.
+ *
+ * @param app Messenger application
+ */
 void
 event_update_profile(MESSENGER_Application *app);
 
+/**
+ * Event for the UI to be called whenever a the user
+ * joins or leaves a chat (context) via message.
+ *
+ * @param app Messenger application
+ * @param context Chat context
+ * @param msg Join/Leave message
+ */
 void
 event_update_chats(MESSENGER_Application *app,
                    struct GNUNET_CHAT_Context *context,
                    const struct GNUNET_CHAT_Message *msg);
 
+/**
+ * Event for the UI to be called whenever a contact
+ * joins or leaves a given context via message.
+ *
+ * @param app Messenger application
+ * @param context Chat context
+ * @param msg Join/Leave message
+ */
 void
 event_presence_contact(MESSENGER_Application *app,
                        struct GNUNET_CHAT_Context *context,
                        const struct GNUNET_CHAT_Message *msg);
 
+/**
+ * Event for the UI to be called whenever a contact
+ * updates their information with a message in a
+ * given context.
+ *
+ * @param app Messenger application
+ * @param context Chat context
+ * @param msg Update message
+ */
 void
 event_update_contacts(MESSENGER_Application *app,
                       struct GNUNET_CHAT_Context *context,
                       const struct GNUNET_CHAT_Message *msg);
 
+/**
+ * Event for the UI to be called whenever an invitation
+ * message gets received in a given context.
+ *
+ * @param app Messenger application
+ * @param context Chat context
+ * @param msg Invitation message
+ */
 void
 event_invitation(MESSENGER_Application *app,
                  struct GNUNET_CHAT_Context *context,
                  const struct GNUNET_CHAT_Message *msg);
 
+/**
+ * Event for the UI to be called whenever a content
+ * message (text or file) gets received in a given
+ * context.
+ *
+ * @param app Messenger application
+ * @param context Chat context
+ * @param msg Message
+ */
 void
 event_receive_message(MESSENGER_Application *app,
                       struct GNUNET_CHAT_Context *context,
                       const struct GNUNET_CHAT_Message *msg);
 
+/**
+ * Event for the UI to be called whenever a message
+ * gets deleted in a given context.
+ *
+ * @param app Messenger application
+ * @param context Chat context
+ * @param msg Delete message
+ */
 void
 event_delete_message(MESSENGER_Application *app,
                      struct GNUNET_CHAT_Context *context,
diff --git a/src/file.h b/src/file.h
index d9bb090..939ac34 100644
--- a/src/file.h
+++ b/src/file.h
@@ -33,21 +33,59 @@ typedef struct MESSENGER_FileInfo
   GList *file_messages;
 } MESSENGER_FileInfo;
 
+/**
+ * Creates a file information struct to potentially update
+ * all GUI appearances of a specific file at once.
+ *
+ * @param file Chat file
+ */
 void
 file_create_info(struct GNUNET_CHAT_File *file);
 
+/**
+ * Destroys and frees resources allocated for a given
+ * file information struct.
+ *
+ * @param file Chat file
+ */
 void
 file_destroy_info(struct GNUNET_CHAT_File *file);
 
+/**
+ * Adds a UI message handle to the list of handles
+ * which get updated by state changes.
+ *
+ * @param file Chat file
+ * @param message UI message handle
+ */
 void
 file_add_ui_message_to_info(const struct GNUNET_CHAT_File *file,
                             UI_MESSAGE_Handle *message);
 
+/**
+ * Updates the connected UI elements for a given
+ * file depending on the current state of its upload
+ * process.
+ *
+ * @param file Chat file
+ * @param completed Amount of uploaded bytes
+ * @param size Size of the file in bytes
+ */
 void
 file_update_upload_info(const struct GNUNET_CHAT_File *file,
                         uint64_t completed,
                         uint64_t size);
 
+/**
+ * Updates the connected UI elements for a given
+ * file depending on the current state of its download
+ * process.
+ *
+ * @param file Chat file
+ * @param app Messenger application
+ * @param completed Amount of downloaded bytes
+ * @param size Size of the file in bytes
+ */
 void
 file_update_download_info(const struct GNUNET_CHAT_File *file,
                           MESSENGER_Application *app,
diff --git a/src/resources.h b/src/resources.h
index 82e8534..2080364 100644
--- a/src/resources.h
+++ b/src/resources.h
@@ -25,9 +25,15 @@
 #ifndef RESOURCES_H_
 #define RESOURCES_H_
 
+/**
+ * Registers the CSS and UI components for the application.
+ */
 void
 resources_register();
 
+/**
+ * Unregisters the CSS and UI components for the application.
+ */
 void
 resources_unregister();
 
diff --git a/src/ui.h b/src/ui.h
index 3c06bcc..7547b0c 100644
--- a/src/ui.h
+++ b/src/ui.h
@@ -28,12 +28,33 @@
 #include <gtk-3.0/gtk/gtk.h>
 #include <libhandy-1/handy.h>
 
+/**
+ * Sets the text of a GtkLabel applying automatic utf8
+ * conversion.
+ *
+ * @param label Label
+ * @param text Non-utf8 text
+ */
 void
 ui_label_set_text(GtkLabel *label, const char *text);
 
+/**
+ * Sets the text of a GtkEntry applying automatic utf8
+ * conversion.
+ *
+ * @param entry Entry
+ * @param text Non-utf8 text
+ */
 void
 ui_entry_set_text(GtkEntry *entry, const char *text);
 
+/**
+ * Sets the text of a HdyAvatar applying automatic utf8
+ * conversion.
+ *
+ * @param avatar Avatar
+ * @param text Non-utf8 text
+ */
 void
 ui_avatar_set_text(HdyAvatar *avatar, const char *text);