diff options
author | TheJackiMonster <thejackimonster@gmail.com> | 2022-04-19 00:31:14 +0200 |
---|---|---|
committer | TheJackiMonster <thejackimonster@gmail.com> | 2022-04-19 00:31:14 +0200 |
commit | fc56c6148f22d363a27c7a39d8d97a2d4d908a92 (patch) | |
tree | a6f7a81785104dbfab204fa3566d243c52415604 | |
parent | 9ad1e9f834085b034262f9724400bcb52b55b70c (diff) |
Added doxygen comments to some headers
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-rw-r--r-- | src/application.h | 52 | ||||
-rw-r--r-- | src/chat/messenger.h | 9 | ||||
-rw-r--r-- | src/contact.h | 46 | ||||
-rw-r--r-- | src/event.h | 72 | ||||
-rw-r--r-- | src/file.h | 38 | ||||
-rw-r--r-- | src/resources.h | 6 | ||||
-rw-r--r-- | src/ui.h | 21 |
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, @@ -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(); @@ -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); |