commit 969f1536918e342bb331acfb042bf906c307978c
parent 18d12007e147e7520e188dac91918ce1a94da409
Author: TheJackiMonster <thejackimonster@gmail.com>
Date: Fri, 9 Sep 2022 20:33:51 +0200
Added documentation comments to the functions
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
Diffstat:
20 files changed, 305 insertions(+), 20 deletions(-)
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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);
