Added GtkDoc style in-code documentation

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)
 {

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;

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;

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)
 {

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)
 {