From 7e78b2b7de565b6b8fc8df5b87f664116e70dbf1 Mon Sep 17 00:00:00 2001 From: Polonkai Gergely Date: Sat, 24 Mar 2012 19:34:36 +0000 Subject: [PATCH] Added GtkDoc style in-code documentation --- src/db.c | 22 +++++++++++ src/interpreter.c | 20 +++++++++- src/interpreter.h | 16 ++++++++ src/main.c | 97 +++++++++++++++++++++++++++++++++++++++++++++-- src/networking.c | 73 ++++++++++++++++++++++++++++++++++- 5 files changed, 221 insertions(+), 7 deletions(-) diff --git a/src/db.c b/src/db.c index 4df3c7c..4d91b9d 100644 --- a/src/db.c +++ b/src/db.c @@ -25,6 +25,12 @@ sqlite3 *dbh = NULL; +/** + * wmud_db_init: + * @error: a GError to put error messages in it + * + * Initializes the wMUD database system. Checks and opens database files. + */ gboolean wmud_db_init(GError **err) { @@ -43,6 +49,12 @@ wmud_db_init(GError **err) return TRUE; } +/** + * wmud_db_players_load: + * @error: a GError to put error messages in it + * + * Loads all player records from the database + */ gboolean wmud_db_players_load(GError **err) { @@ -95,6 +107,16 @@ wmud_db_players_load(GError **err) return FALSE; } +/** + * wmud_db_save_player: + * @player: the player record to save + * @error: a GError to put error messages in it + * + * Saves a player record to the database backend. + * + * Return value: %TRUE on success. Upon failure, %FALSE is returned, and err is + * set accordingly. + */ gboolean wmud_db_save_player(wmudPlayer *player, GError **err) { diff --git a/src/interpreter.c b/src/interpreter.c index 47fbd66..4e13692 100644 --- a/src/interpreter.c +++ b/src/interpreter.c @@ -33,12 +33,25 @@ static wmudCommand command_list[] = { { NULL, NULL }, }; +/** + * destroy_string: + * @string: a GString to destroy + * + * Callback function to destroy a list of GStrings + */ static void destroy_string(GString *string) { g_string_free(string, TRUE); } +/** + * wmud_interpret_game_command: + * @client: the wmudClient whose command should be processed + * + * Processes a wmudClient's buffer, and executes the game command if there is + * one + */ void wmud_interpret_game_command(wmudClient *client) { @@ -176,7 +189,12 @@ wmud_interpret_game_command(wmudClient *client) g_slist_free(matches); } -WMUD_COMMAND(gcmd_quit) +/** + * gcmd_quit: + * + * The QUIT game command's handler + */ +WMUD_COMMAND(quit) { wmud_client_send(client, "Are you sure you want to get back to that freaky other reality? [y/N] "); client->state = WMUD_CLIENT_STATE_QUITWAIT; diff --git a/src/interpreter.h b/src/interpreter.h index e479675..8f42b57 100644 --- a/src/interpreter.h +++ b/src/interpreter.h @@ -21,9 +21,25 @@ #include "networking.h" +/** + * wmudCommandFunc: + * @client: the client from whom the command arrived + * @command: the command itself + * @token_list: the command arguments + * + * Command handler function type + */ typedef void (*wmudCommandFunc)(wmudClient *client, gchar *command, GSList *token_list); #define WMUD_COMMAND(name) void name(wmudClient *client, gchar *command, GSList *token_list) +/** + * wmudCommand: + * @command: the command itself. Should be in uppercase, but doesn't actually + * matter + * @commandFunc: the command handler function for this command + * + * This structure holds the different properties of the in-game commands. + */ typedef struct _wmudCommand { gchar *command; wmudCommandFunc commandFunc; diff --git a/src/main.c b/src/main.c index a281488..b2f3fb6 100644 --- a/src/main.c +++ b/src/main.c @@ -33,11 +33,30 @@ #include "db.h" #include "players.h" +/** + * debug_context_loc: + * + * This variable holds the location of the last context marker + */ struct { char *file; int line; } debug_context_loc = {NULL, 0}; +/** + * @game_context: the game thread's main context + * @elapsed_seconds: the number of seconds elapsed since game boot. May be + * inaccurate, as it simply gets updated by a timeout + * function which should run every second + * @elapsed_cycle: yes, I'm optimistic. This counter is increased if, for some + * reason, #elapsed_seconds reaches the maximum value + * @main_rand: the main random generator + * @WMUD_CONFIG_ERROR: the GQuark for the config error GError + * @WMUD_DB_ERROR: the GQuark for the database error GError + * @port: the port number to listen on + * @database_file: the filename of the world database + * @admin_email: e-mail address of the MUD's administrator + */ GMainContext *game_context; guint32 elapsed_seconds = 0; guint32 elapsed_cycle = 0; @@ -48,10 +67,12 @@ guint port = 0; gchar *database_file = NULL; gchar *admin_email = NULL; -/* rl_sec_elapsed() +/** + * rl_sec_elapsed: + * @user_data: non-used pointer to callback's user data * - * This function keeps track of elapsed real-world time. It is inaccurate by - * design, but it doesn't actually matter. + * Keeps track of elapsed real-world time. It is inaccurate by design, but it + * doesn't actually matter. */ gboolean rl_sec_elapsed(gpointer user_data) @@ -71,6 +92,12 @@ rl_sec_elapsed(gpointer user_data) return TRUE; } +/** + * wmud_random_string: + * @len: the desired length of the generated random string + * + * Generates a random string of %len characters. + */ gchar * wmud_random_string(gint len) { @@ -91,6 +118,14 @@ wmud_random_string(gint len) return ret; } +/** + * wmud_maintenance_check_new_players: + * @player: #wmudPLayer structure of the player record to check + * @user_data: not used + * + * Callback called from within the maintenance loop. Checks if the player has + * an unset password, and generate one for them, if so. + */ void wmud_maintenance_check_new_players(wmudPlayer *player, gpointer user_data) { @@ -120,6 +155,12 @@ wmud_maintenance_check_new_players(wmudPlayer *player, gpointer user_data) } } +/** + * wmud_maintenance: + * @user_data: not used + * + * Timeout source function for maintenance tasks + */ gboolean wmud_maintenance(gpointer user_data) { @@ -135,11 +176,16 @@ wmud_maintenance(gpointer user_data) #ifdef DEBUG void -/* debug_context() +/** + * debug_context: + * @file: the source file name, where the context marker was found + * @line: the line number where the context marker was found * * This function keeps track of the code flow in some way. It can help with * debugging, as during a SIGSEGV or such signal this will print out the last * place of DebugContext in the code. + * + * THIS FUNCTION SHOULD NEVER BE CALLED DIRECTLY! */ debug_context(char *file, int line) { @@ -149,11 +195,22 @@ debug_context(char *file, int line) debug_context_loc.file = g_strdup(file); debug_context_loc.line = line; } +/** + * DebugContext: + * + * Marks the current line of the source file with a context marker. Deadly + * signals should print the place of the last marker. + */ #define DebugContext debug_context(__FILE__, __LINE__) #else #define DebugContext #endif +/** + * wmud_type_init: + * + * Initializes the wMUD types. + */ void wmud_type_init(void) { @@ -161,6 +218,15 @@ wmud_type_init(void) WMUD_DB_ERROR = g_quark_from_string("wmud_db_error"); } +/** + * wmud_config_init: + * @err: The GError in which the config handling status should be returned + * + * Parses the default configuration file, and sets different variables + * according to it. + * + * Return value: %TRUE if parsing was successful. %FALSE otherwise. + */ gboolean wmud_config_init(GError **err) { @@ -240,6 +306,14 @@ wmud_config_init(GError **err) return TRUE; } +/** + * game_thread_func: + * @game_loop: the main loop to be associated with the game thread + * + * The game thread's main function. + * + * Return value: This function always returns %NULL. + */ gpointer game_thread_func(GMainLoop *game_loop) { @@ -249,6 +323,14 @@ game_thread_func(GMainLoop *game_loop) return NULL; } +/** + * maint_thread_func: + * @main_loop: the main loop to be associated with the maintenance thread + * + * The maintenance thread's main function. + * + * Return value: This function always returns %NULL. + */ gpointer maint_thread_func(GMainLoop *maint_loop) { @@ -257,6 +339,13 @@ maint_thread_func(GMainLoop *maint_loop) return NULL; } +/** + * main: + * @argc: The number of arguments on the command line + * @argv: The command line arguments themselves + * + * The Main Function (TM) + */ int main(int argc, char **argv) { diff --git a/src/networking.c b/src/networking.c index fb30bb3..b7cf55e 100644 --- a/src/networking.c +++ b/src/networking.c @@ -41,6 +41,15 @@ GSList *clients; void wmud_client_interpret_newplayer_email(wmudClient *client); void wmud_client_interpret_newplayer_mailconfirm(wmudClient *client_data); +/** + * wmud_client_close: + * @client: the client whose connection should be dropped + * @send_goodbye: if set to %TRUE, we will send a nice good-bye message to the + * client before dropping the connection + * + * Closes a client connection. If send_goodbye is set to %TRUE, a good-bye + * message will be sent to the client. + */ void wmud_client_close(wmudClient *client, gboolean send_goodbye) { @@ -57,6 +66,14 @@ wmud_client_close(wmudClient *client, gboolean send_goodbye) g_free(client); } +/** + * wmud_client_callback: + * @client: the socket of the client on which the data arrived + * @condition: the condition available on the client socket + * @client: the wmudClient structure of the client + * + * Processes incoming client data, and client hangup + */ static gboolean wmud_client_callback(GSocket *client, GIOCondition condition, wmudClient *client_data) { @@ -195,9 +212,16 @@ wmud_client_callback(GSocket *client, GIOCondition condition, wmudClient *client return TRUE; } -/* game_source_callback() +/** + * game_source_callback: + * @socket: the listener socket on which the new connection arrived + * @condition: not used + * @accept_data: the AcceptData structure of the game listener * - * This function is called whenever a new connection is available on the game socket + * Callback function to be called when a new connection is available on the + * game listener socket. + * + * Return value: this function always returns %TRUE */ gboolean game_source_callback(GSocket *socket, GIOCondition condition, struct AcceptData *accept_data) @@ -226,6 +250,16 @@ game_source_callback(GSocket *socket, GIOCondition condition, struct AcceptData return TRUE; } +/** + * wmud_networking_init: + * @port_number: the port number on which the game listener should listen + * @err: the GError in which possible errors will be reported + * + * Initializes the game network listener + * + * Return value: Returns %TRUE on success. Upon failure, %FALSE is return, and + * err is set accordingly (if not NULL) + */ gboolean wmud_networking_init(guint port_number, GError **err) { @@ -338,6 +372,14 @@ wmud_networking_init(guint port_number, GError **err) return TRUE; } +/** + * wmud_client_send: + * @client: the client to which the message will be sent + * @fmt: the printf() style format string of the message + * @...: optional parameters to the format string + * + * Sends a formatted message to a game client + */ void wmud_client_send(wmudClient *client, const gchar *fmt, ...) { @@ -353,6 +395,13 @@ wmud_client_send(wmudClient *client, const gchar *fmt, ...) g_string_free(buf, TRUE); } +/** + * wmud_client_start_login: + * @client: the client from which the login name came from + * + * This function is currently called when the freshly connected client sends a + * non-empty string (a player name). + */ void wmud_client_start_login(wmudClient *client) { @@ -382,6 +431,13 @@ wmud_client_start_login(wmudClient *client) } } +/** + * wmud_client_interpret_newplayer_answer: + * @client: the client from which the answer came from + * + * Interprets a yes/no answer from the client to the question if they are new + * to the game. + */ void wmud_client_interpret_newplayer_answer(wmudClient *client) { @@ -402,6 +458,12 @@ wmud_client_interpret_newplayer_answer(wmudClient *client) } } +/** + * wmud_client_interpret_newplayer_email: + * @client: the client from which the e-mail address arrived from + * + * Checks for the validity of the new player's e-mail address + */ void wmud_client_interpret_newplayer_email(wmudClient *client) { @@ -430,6 +492,13 @@ wmud_client_interpret_newplayer_email(wmudClient *client) } } +/** + * wmud_client_interpret_newplayer_mailconfirm: + * @client: the client from which the confirmation e-mail arrived + * + * Check if the confirmed e-mail address is the same as the previously entered + * one. + */ void wmud_client_interpret_newplayer_mailconfirm(wmudClient *client) {