Added documentation comments to the functions

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

20 files changed, 305 insertions, 20 deletions

diff --git a/src/application.h b/src/application.h
index 75bf336..ea248e0 100644
--- a/src/application.h
+++ b/src/application.h
@@ -35,6 +35,9 @@
 #include "ui/chat.h"
 #include "ui/chats.h"
 
+/**
+ * @struct MESSENGER_Application
+ */
 typedef struct MESSENGER_Application
 {
   char **argv;
@@ -58,20 +61,54 @@ typedef struct MESSENGER_Application
   UI_CHAT_Handle current;
 } MESSENGER_Application;
 
+/**
+ * Clears the application handle to reset all views
+ * which might have been in use.
+ *
+ * @param[out] app Application handle
+ */
 void
 application_clear(MESSENGER_Application *app);
 
+/**
+ * Initializes the application handle with the program
+ * arguments provided from the main function.
+ *
+ * @param[out] app Application handle
+ * @param[in] argc Argument count
+ * @param[in] argv Argument array
+ */
 void
 application_init(MESSENGER_Application *app,
                  int argc,
                  char **argv);
 
+/**
+ * Refreshes the application handle freeing all temporary
+ * WINDOW handles to manage the different views which
+ * were used.
+ *
+ * @param[out] app Application handle
+ */
 void
 application_refresh(MESSENGER_Application *app);
 
+/**
+ * Starts the main loop of the application which will
+ * be processed via GNUnet and its callback management.
+ *
+ * @param[in,out] app Application handle
+ */
 void
 application_run(MESSENGER_Application *app);
 
+/**
+ * Returns the status code by the given application
+ * at current state.
+ *
+ * @param[in] app Application handle
+ * @return #EXIT_FAILURE on failure, otherwise #EXIT_SUCCESS
+ */
 int
 application_status(MESSENGER_Application *app);
 
diff --git a/src/chat.h b/src/chat.h
index 5422e3b..7eb103f 100644
--- a/src/chat.h
+++ b/src/chat.h
@@ -31,6 +31,9 @@
 
 struct MESSENGER_Application;
 
+/**
+ * @struct MESSENGER_Chat
+ */
 typedef struct MESSENGER_Chat
 {
   struct GNUNET_CHAT_Handle *handle;
@@ -42,18 +45,49 @@ typedef struct MESSENGER_Chat
   bool quit;
 } MESSENGER_Chat;
 
+/**
+ * Starts the processing of the given applications
+ * chat handle.
+ *
+ * @param[out] chat Application chat handle
+ * @param[in,out] app Application handle
+ * @param[in] cfg Configuration
+ */
 void
 chat_start(MESSENGER_Chat *chat,
            struct MESSENGER_Application *app,
            const struct GNUNET_CONFIGURATION_Handle *cfg);
 
+/**
+ * Stops the processing of the given applications
+ * chat handle.
+ *
+ * @param[in,out] chat Application chat handle
+ */
 void
 chat_stop(MESSENGER_Chat *chat);
 
+/**
+ * Updates the layout of the applications views depending
+ * on the main windows resolution and the current state
+ * of the applications chat handle.
+ *
+ * @param[in] chat Application chat handle
+ * @param[out] app Application handle
+ */
 void
 chat_update_layout(MESSENGER_Chat *chat,
                    struct MESSENGER_Application *app);
 
+/**
+ * Processes a chat message to update the list of
+ * required resources to handle visual representation
+ * of current members in a chat or the messages.
+ *
+ * @param[in,out] chat Application chat handle
+ * @param[in] context Chat context of the message
+ * @param[in] message Chat message
+ */
 void
 chat_process_message(MESSENGER_Chat *chat,
                      struct GNUNET_CHAT_Context *context,
diff --git a/src/ui/account_create_dialog.c b/src/ui/account_create_dialog.c
index f3c9394..1ef6568 100644
--- a/src/ui/account_create_dialog.c
+++ b/src/ui/account_create_dialog.c
@@ -59,8 +59,7 @@ account_create_dialog_event(UI_ACCOUNT_CREATE_DIALOG_Handle *create_dialog,
 }
 
 void
-account_create_dialog_print(UI_ACCOUNT_CREATE_DIALOG_Handle *create_dialog,
-                            UNUSED struct MESSENGER_Application *app)
+account_create_dialog_print(UI_ACCOUNT_CREATE_DIALOG_Handle *create_dialog)
 {
   if (!(create_dialog->window))
     return;
diff --git a/src/ui/account_create_dialog.h b/src/ui/account_create_dialog.h
index d42fef2..93c8318 100644
--- a/src/ui/account_create_dialog.h
+++ b/src/ui/account_create_dialog.h
@@ -30,6 +30,9 @@
 
 struct MESSENGER_Application;
 
+/**
+ * @struct UI_ACCOUNT_CREATE_DIALOG_Handle
+ */
 typedef struct UI_ACCOUNT_CREATE_DIALOG_Handle
 {
   WINDOW **window;
@@ -39,13 +42,26 @@ typedef struct UI_ACCOUNT_CREATE_DIALOG_Handle
   int name_pos;
 } UI_ACCOUNT_CREATE_DIALOG_Handle;
 
+/**
+ * Processes the current key event by the dialog
+ * to create a new account.
+ *
+ * @param[in,out] create_dialog Account creation dialog
+ * @param[in,out] app Application handle
+ * @param[in] key Key
+ */
 void
 account_create_dialog_event(UI_ACCOUNT_CREATE_DIALOG_Handle *create_dialog,
                             struct MESSENGER_Application *app,
                             int key);
 
+/**
+ * Prints the content of the dialog to create a new
+ * account to its selected window view.
+ *
+ * @param[in] create_dialog Account creation dialog
+ */
 void
-account_create_dialog_print(UI_ACCOUNT_CREATE_DIALOG_Handle *create_dialog,
-                            struct MESSENGER_Application *app);
+account_create_dialog_print(UI_ACCOUNT_CREATE_DIALOG_Handle *create_dialog);
 
 #endif /* UI_ACCOUNT_CREATE_DIALOG_H_ */
diff --git a/src/ui/accounts.c b/src/ui/accounts.c
index 380506d..bdc5086 100644
--- a/src/ui/accounts.c
+++ b/src/ui/accounts.c
@@ -114,7 +114,7 @@ accounts_print(UI_ACCOUNTS_Handle *accounts,
 {
   if (accounts->create_dialog.window)
   {
-    account_create_dialog_print(&(accounts->create_dialog), app);
+    account_create_dialog_print(&(accounts->create_dialog));
     return;
   }
 
diff --git a/src/ui/accounts.h b/src/ui/accounts.h
index 4e278d5..2566e78 100644
--- a/src/ui/accounts.h
+++ b/src/ui/accounts.h
@@ -36,6 +36,9 @@
 
 struct MESSENGER_Application;
 
+/**
+ * @struct UI_ACCOUNTS_Handle
+ */
 typedef struct UI_ACCOUNTS_Handle
 {
   WINDOW *window;
@@ -55,11 +58,27 @@ typedef struct UI_ACCOUNTS_Handle
 #define UI_ACCOUNTS_ROWS_MIN 5
 #define UI_ACCOUNTS_COLS_MIN 30
 
+/**
+ * Processes the current key event by the view
+ * to show the list of chat accounts.
+ *
+ * @param[in,out] accounts Chat accounts view
+ * @param[in,out] app Application handle
+ * @param[in] key Key
+ */
 void
 accounts_event(UI_ACCOUNTS_Handle *accounts,
                struct MESSENGER_Application *app,
                int key);
 
+/**
+ * Prints the content of the view to show
+ * the list of chat accounts to its selected
+ * window view on screen.
+ *
+ * @param[in,out] accounts Chat accounts view
+ * @param[in] app Application handle
+ */
 void
 accounts_print(UI_ACCOUNTS_Handle *accounts,
                struct MESSENGER_Application *app);
diff --git a/src/ui/chat.h b/src/ui/chat.h
index b8febf4..582ba66 100644
--- a/src/ui/chat.h
+++ b/src/ui/chat.h
@@ -28,6 +28,9 @@
 #include "members.h"
 #include "messages.h"
 
+/**
+ * @struct UI_CHAT_Handle
+ */
 typedef struct UI_CHAT_Handle
 {
   UI_MEMBERS_Handle members;
diff --git a/src/ui/chat_open_dialog.c b/src/ui/chat_open_dialog.c
index 5b641d6..cd98401 100644
--- a/src/ui/chat_open_dialog.c
+++ b/src/ui/chat_open_dialog.c
@@ -59,8 +59,7 @@ chat_open_dialog_event(UI_CHAT_OPEN_DIALOG_Handle *open_dialog,
 }
 
 void
-chat_open_dialog_print(UI_CHAT_OPEN_DIALOG_Handle *open_dialog,
-                       UNUSED struct MESSENGER_Application *app)
+chat_open_dialog_print(UI_CHAT_OPEN_DIALOG_Handle *open_dialog)
 {
   if (!(open_dialog->window))
     return;
diff --git a/src/ui/chat_open_dialog.h b/src/ui/chat_open_dialog.h
index 0367abc..413d15e 100644
--- a/src/ui/chat_open_dialog.h
+++ b/src/ui/chat_open_dialog.h
@@ -30,6 +30,9 @@
 
 struct MESSENGER_Application;
 
+/**
+ * @struct UI_CHAT_OPEN_DIALOG_Handle
+ */
 typedef struct UI_CHAT_OPEN_DIALOG_Handle
 {
   WINDOW **window;
@@ -39,13 +42,26 @@ typedef struct UI_CHAT_OPEN_DIALOG_Handle
   int topic_pos;
 } UI_CHAT_OPEN_DIALOG_Handle;
 
+/**
+ * Processes the current key event by the dialog
+ * to open a chat.
+ *
+ * @param[in,out] open_dialog Chat opening dialog
+ * @param[in,out] app Application handle
+ * @param[in] key Key
+ */
 void
 chat_open_dialog_event(UI_CHAT_OPEN_DIALOG_Handle *open_dialog,
                        struct MESSENGER_Application *app,
                        int key);
 
+/**
+ * Prints the content of the dialog to open a
+ * chat to its selected window view.
+ *
+ * @param[in] open_dialog Chat opening dialog
+ */
 void
-chat_open_dialog_print(UI_CHAT_OPEN_DIALOG_Handle *open_dialog,
-                       struct MESSENGER_Application *app);
+chat_open_dialog_print(UI_CHAT_OPEN_DIALOG_Handle *open_dialog);
 
 #endif /* UI_CHAT_OPEN_DIALOG_H_ */
diff --git a/src/ui/chats.c b/src/ui/chats.c
index c2cc2ae..55e08df 100644
--- a/src/ui/chats.c
+++ b/src/ui/chats.c
@@ -191,17 +191,17 @@ chats_print(UI_CHATS_Handle *chats,
 {
   if (chats->open_dialog.window)
   {
-    chat_open_dialog_print(&(chats->open_dialog), app);
+    chat_open_dialog_print(&(chats->open_dialog));
     return;
   }
   else if (chats->create_dialog.win)
   {
-    lobby_create_dialog_print(&(chats->create_dialog), app);
+    lobby_create_dialog_print(&(chats->create_dialog));
     return;
   }
   else if (chats->enter_dialog.window)
   {
-    lobby_enter_dialog_print(&(chats->enter_dialog), app);
+    lobby_enter_dialog_print(&(chats->enter_dialog));
     return;
   }
 
diff --git a/src/ui/chats.h b/src/ui/chats.h
index 8e836bd..7ab64d5 100644
--- a/src/ui/chats.h
+++ b/src/ui/chats.h
@@ -38,6 +38,9 @@
 
 struct MESSENGER_Application;
 
+/**
+ * @struct UI_CHATS_Handle
+ */
 typedef struct UI_CHATS_Handle
 {
   WINDOW *window;
@@ -59,11 +62,27 @@ typedef struct UI_CHATS_Handle
 #define UI_CHATS_ROWS_MIN 8
 #define UI_CHATS_COLS_MIN 30
 
+/**
+ * Processes the current key event by the view
+ * to show the list of available chats.
+ *
+ * @param[in,out] chats Chats view
+ * @param[in,out] app Application handle
+ * @param[in] key Key
+ */
 void
 chats_event(UI_CHATS_Handle *chats,
             struct MESSENGER_Application *app,
             int key);
 
+/**
+ * Prints the content of the view to show
+ * the list of available chats to its selected
+ * window view on screen.
+ *
+ * @param[in,out] chats Chats view
+ * @param[in] app Application handle
+ */
 void
 chats_print(UI_CHATS_Handle *chats,
             struct MESSENGER_Application *app);
diff --git a/src/ui/list_input.h b/src/ui/list_input.h
index 717e1ba..4fea1f4 100644
--- a/src/ui/list_input.h
+++ b/src/ui/list_input.h
@@ -28,6 +28,9 @@
 #include <stdbool.h>
 #include <stdlib.h>
 
+/**
+ * Resets the list controls.
+ */
 #define list_input_reset(list) { \
   (list)->line_prev = 0;         \
   (list)->line_next = 0;         \
@@ -35,6 +38,10 @@
   (list)->selected = 0;          \
 }
 
+/**
+ * Handles the list controls selection and
+ * indices to move the selection via events.
+ */
 #define list_input_select(list, line_width, item) {                \
   const bool selected = (                                          \
       ((list)->line_selected >= (list)->line_index) &&             \
@@ -52,6 +59,10 @@
   }                                                                \
 }
 
+/**
+ * Handles the key event to move the selection
+ * of list controls and adjust its view area.
+ */
 #define list_input_event(list, key) {                          \
   int count = (list)->line_index;                              \
                                                                \
@@ -93,6 +104,11 @@
   }                                                            \
 }
 
+/**
+ * Prepares for printing an item in list controls
+ * as well as providing its selection and its
+ * y location in the current view.
+ */
 #define list_input_print_(list, line_width, yes_res, no_res)      \
   const bool selected = (                                         \
       ((list)->line_selected >= (list)->line_index) &&            \
diff --git a/src/ui/lobby_create_dialog.c b/src/ui/lobby_create_dialog.c
index f294391..61c1a4c 100644
--- a/src/ui/lobby_create_dialog.c
+++ b/src/ui/lobby_create_dialog.c
@@ -121,8 +121,7 @@ _lobby_iterate_print(UI_LOBBY_CREATE_DIALOG_Handle *create_dialog,
 }
 
 void
-lobby_create_dialog_print(UI_LOBBY_CREATE_DIALOG_Handle *create_dialog,
-                          UNUSED struct MESSENGER_Application *app)
+lobby_create_dialog_print(UI_LOBBY_CREATE_DIALOG_Handle *create_dialog)
 {
   if (!(create_dialog->win))
     return;
diff --git a/src/ui/lobby_create_dialog.h b/src/ui/lobby_create_dialog.h
index 1497255..42d06fc 100644
--- a/src/ui/lobby_create_dialog.h
+++ b/src/ui/lobby_create_dialog.h
@@ -34,6 +34,9 @@
 
 struct MESSENGER_Application;
 
+/**
+ * @struct UI_LOBBY_CREATE_DIALOG_Handle
+ */
 typedef struct UI_LOBBY_CREATE_DIALOG_Handle
 {
   WINDOW *window;
@@ -52,13 +55,26 @@ typedef struct UI_LOBBY_CREATE_DIALOG_Handle
   char *uri;
 } UI_LOBBY_CREATE_DIALOG_Handle;
 
+/**
+ * Processes the current key event by the dialog
+ * to create a lobby.
+ *
+ * @param[in,out] create_dialog Lobby creation dialog
+ * @param[in,out] app Application handle
+ * @param[in] key Key
+ */
 void
 lobby_create_dialog_event(UI_LOBBY_CREATE_DIALOG_Handle *create_dialog,
                           struct MESSENGER_Application *app,
                           int key);
 
+/**
+ * Prints the content of the dialog to create a
+ * lobby to its selected window view.
+ *
+ * @param[in] create_dialog Lobby creation dialog
+ */
 void
-lobby_create_dialog_print(UI_LOBBY_CREATE_DIALOG_Handle *create_dialog,
-                          struct MESSENGER_Application *app);
+lobby_create_dialog_print(UI_LOBBY_CREATE_DIALOG_Handle *create_dialog);
 
 #endif /* UI_LOBBY_CREATE_DIALOG_H_ */
diff --git a/src/ui/lobby_enter_dialog.c b/src/ui/lobby_enter_dialog.c
index 6de4d1c..0ae9018 100644
--- a/src/ui/lobby_enter_dialog.c
+++ b/src/ui/lobby_enter_dialog.c
@@ -78,8 +78,7 @@ lobby_enter_dialog_event(UI_LOBBY_ENTER_DIALOG_Handle *enter_dialog,
 }
 
 void
-lobby_enter_dialog_print(UI_LOBBY_ENTER_DIALOG_Handle *enter_dialog,
-                         UNUSED struct MESSENGER_Application *app)
+lobby_enter_dialog_print(UI_LOBBY_ENTER_DIALOG_Handle *enter_dialog)
 {
   if (!(enter_dialog->window))
     return;
diff --git a/src/ui/lobby_enter_dialog.h b/src/ui/lobby_enter_dialog.h
index 81ddeac..8e7cc05 100644
--- a/src/ui/lobby_enter_dialog.h
+++ b/src/ui/lobby_enter_dialog.h
@@ -30,6 +30,9 @@
 
 struct MESSENGER_Application;
 
+/**
+ * @struct UI_LOBBY_ENTER_DIALOG_Handle
+ */
 typedef struct UI_LOBBY_ENTER_DIALOG_Handle
 {
   WINDOW **window;
@@ -41,13 +44,26 @@ typedef struct UI_LOBBY_ENTER_DIALOG_Handle
   int uri_pos;
 } UI_LOBBY_ENTER_DIALOG_Handle;
 
+/**
+ * Processes the current key event by the dialog
+ * to enter a lobby.
+ *
+ * @param[in,out] enter_dialog Lobby entry dialog
+ * @param[in,out] app Application handle
+ * @param[in] key Key
+ */
 void
 lobby_enter_dialog_event(UI_LOBBY_ENTER_DIALOG_Handle *enter_dialog,
                          struct MESSENGER_Application *app,
                          int key);
 
+/**
+ * Prints the content of the dialog to enter a
+ * lobby to its selected window view.
+ *
+ * @param[in] enter_dialog Lobby entry dialog
+ */
 void
-lobby_enter_dialog_print(UI_LOBBY_ENTER_DIALOG_Handle *enter_dialog,
-                         struct MESSENGER_Application *app);
+lobby_enter_dialog_print(UI_LOBBY_ENTER_DIALOG_Handle *enter_dialog);
 
 #endif /* UI_LOBBY_ENTER_DIALOG_H_ */
diff --git a/src/ui/members.h b/src/ui/members.h
index 62c564f..7769e74 100644
--- a/src/ui/members.h
+++ b/src/ui/members.h
@@ -35,6 +35,9 @@
 
 struct MESSENGER_Application;
 
+/**
+ * @struct UI_MEMBERS_List
+ */
 typedef struct UI_MEMBERS_List
 {
   struct GNUNET_CHAT_Contact *contact;
@@ -43,6 +46,9 @@ typedef struct UI_MEMBERS_List
   struct UI_MEMBERS_List *next;
 } UI_MEMBERS_List;
 
+/**
+ * @struct UI_MEMBERS_Handle
+ */
 typedef struct UI_MEMBERS_Handle
 {
   WINDOW *window;
@@ -62,21 +68,59 @@ typedef struct UI_MEMBERS_Handle
 
 #define UI_MEMBERS_COLS_MIN 30
 
+/**
+ * Processes the current key event by the view
+ * to show a chats list of members.
+ *
+ * @param[in,out] members Chat members view
+ * @param[in,out] app Application handle
+ * @param[in] key Key
+ */
 void
 members_event(UI_MEMBERS_Handle *members,
               struct MESSENGER_Application *app,
               int key);
 
+/**
+ * Prints the content of the view to show
+ * a chats list of members to its selected
+ * window view on screen.
+ *
+ * @param[in,out] members Chat members view
+ */
 void
 members_print(UI_MEMBERS_Handle *members);
 
+/**
+ * Clears the list of members the view
+ * would print to the screen.
+ *
+ * @param[out] members Chat members view
+ */
 void
 members_clear(UI_MEMBERS_Handle *members);
 
+/**
+ * Adds a new chat contact to the list of
+ * members the view will print to the
+ * screen.
+ *
+ * @param[in,out] members Chat members view
+ * @param[in] contact Chat contact
+ * @return #TRUE if the member is new, otherwise #FALSE
+ */
 bool
 members_add(UI_MEMBERS_Handle *members,
             struct GNUNET_CHAT_Contact *contact);
 
+/**
+ * Removes a chat contact from the list of
+ * members the view would print to the
+ * screen.
+ *
+ * @param[in,out] members Chat members view
+ * @param[in] contact Chat contact
+ */
 void
 members_remove(UI_MEMBERS_Handle *members,
                const struct GNUNET_CHAT_Contact *contact);
diff --git a/src/ui/messages.h b/src/ui/messages.h
index edc3192..3d509db 100644
--- a/src/ui/messages.h
+++ b/src/ui/messages.h
@@ -34,6 +34,9 @@
 
 struct MESSENGER_Application;
 
+/**
+ * @struct UI_MESSAGES_List
+ */
 typedef struct UI_MESSAGES_List
 {
   time_t timestamp;
@@ -46,6 +49,9 @@ typedef struct UI_MESSAGES_List
 
 #define TEXT_LEN_MAX 1024
 
+/**
+ * @struct UI_MESSAGES_Handle
+ */
 typedef struct UI_MESSAGES_Handle
 {
   WINDOW *window;
@@ -73,21 +79,58 @@ typedef struct UI_MESSAGES_Handle
 #define UI_MESSAGES_FILE_PREFIX "file:"
 #define UI_MESSAGES_FILE_PREFIX_LEN 5
 
+/**
+ * Processes the current key event by the view
+ * to show a chats list of messages.
+ *
+ * @param[in,out] messages Chat messages view
+ * @param[in,out] app Application handle
+ * @param[in] key Key
+ */
 void
 messages_event(UI_MESSAGES_Handle *messages,
                struct MESSENGER_Application *app,
                int key);
 
+/**
+ * Prints the content of the view to show
+ * a chats list of messages to its selected
+ * window view on screen.
+ *
+ * @param[in,out] messages Chat messages view
+ */
 void
 messages_print(UI_MESSAGES_Handle *messages);
 
+/**
+ * Clears the list of messages the view
+ * would print to the screen.
+ *
+ * @param[out] messages Chat messages view
+ */
 void
 messages_clear(UI_MESSAGES_Handle *messages);
 
+/**
+ * Adds a new chat message to the list of
+ * messages the view will print to the
+ * screen.
+ *
+ * @param[in,out] messages Chat messages view
+ * @param[in] message Chat message
+ */
 void
 messages_add(UI_MESSAGES_Handle *messages,
              const struct GNUNET_CHAT_Message *message);
 
+/**
+ * Removes a chat message from the list of
+ * messages the view would print to the
+ * screen.
+ *
+ * @param[in,out] messages Chat messages view
+ * @param[in] message Chat message
+ */
 void
 messages_remove(UI_MESSAGES_Handle *messages,
                 const struct GNUNET_CHAT_Message *message);
diff --git a/src/ui/text_input.h b/src/ui/text_input.h
index 8dc416f..ec04ed5 100644
--- a/src/ui/text_input.h
+++ b/src/ui/text_input.h
@@ -27,6 +27,10 @@
 
 #include <ctype.h>
 
+/**
+ * Handles the key event to move the cursor
+ * and adjust the content of text controls.
+ */
 #define text_input_event(text, key) {                     \
   switch (key)                                           \
   {                                                      \
diff --git a/src/util.h b/src/util.h
index 367eec9..ba4c735 100644
--- a/src/util.h
+++ b/src/util.h
@@ -34,6 +34,12 @@
 #define UTIL_LOGO_ROWS 10
 #define UTIL_LOGO_COLS 28
 
+/**
+ * Prints the main logo of the application
+ * onto a specified view.
+ *
+ * @param[in,out] window Window view
+ */
 void
 util_print_logo(WINDOW *window);