Finished GtkDoc style code documenting.

Added full GtkDoc support
Fixed code comment blocks

Signed-off-by: Gergely POLONKAI <polesz@w00d5t0ck.info>

src/db.c

@@ -23,11 +23,18 @@
 #include "db.h"
 #include "players.h"
 
+/**
+ * SECTION:db
+ * @short_description: Database handling
+ * @title: Database handling routines
+ *
+ */
+
 sqlite3 *dbh = NULL;
 
 /**
  * wmud_db_init:
- * @error: a GError to put error messages in it
+ * @err: a GError to put error messages in it
  *
  * Initializes the wMUD database system. Checks and opens database files.
  */
@@ -51,7 +58,7 @@ wmud_db_init(GError **err)
 
 /**
  * wmud_db_players_load:
- * @error: a GError to put error messages in it
+ * @err: a GError to put error messages in it
  *
  * Loads all player records from the database
  */
@@ -110,7 +117,7 @@ wmud_db_players_load(GError **err)
 /**
  * wmud_db_save_player:
  * @player: the player record to save
- * @error: a GError to put error messages in it
+ * @err: a GError to put error messages in it
  *
  * Saves a player record to the database backend.
  *

src/interpreter.c

@@ -24,6 +24,13 @@
 #include "networking.h"
 #include "main.h"
 
+/**
+ * SECTION:interpreter
+ * @short_description: Game command interpreter
+ *
+ * Functions to interpret and execute in-game commands
+ */
+
 WMUD_COMMAND(quit);
 
 static wmudCommand command_list[] = {

src/main.c

@@ -34,6 +34,13 @@
 #include "players.h"
 #include "maintenance.h"
 
+/**
+ * SECTION:utils
+ * @short_description: Utilities and uncategorized functions
+ * @title: Utility and uncategorized functions
+ *
+ */
+
 /**
  * debug_context_loc:
  *
@@ -45,27 +52,60 @@ struct {
 } 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
+ * game_context:
+ *
+ * the game thread's main context
  */
 GMainContext *game_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
+ */
 guint32 elapsed_seconds = 0;
+/**
+ * elapsed_cycle:
+ *
+ * yes, I'm optimistic. This counter is increased if, for some reason,
+ * #elapsed_seconds reaches the maximum value
+ */
 guint32 elapsed_cycle = 0;
+/**
+ * main_rand:
+ *
+ * the main random generator
+ */
 GRand *main_rand = NULL;
+/**
+ * WMUD_CONFIG_ERROR:
+ *
+ * the GQuark for the config error GError
+ */
 GQuark WMUD_CONFIG_ERROR = 0;
+/**
+ * WMUD_DB_ERROR:
+ *
+ * the GQuark for the database error GError
+ */
 GQuark WMUD_DB_ERROR = 0;
+/**
+ * port:
+ *
+ * the port number to listen on
+ */
 guint port = 0;
+/**
+ * database_file:
+ *
+ * the filename of the world database
+ */
 gchar *database_file = NULL;
+/**
+ * admin_email:
+ *
+ * e-mail address of the MUD's administrator
+ */
 gchar *admin_email = NULL;
 
 /**

src/networking.c

@@ -31,6 +31,13 @@
 #include "players.h"
 #include "db.h"
 
+/**
+ * SECTION:networking
+ * @short_description: Game related networking code
+ *
+ * Functions to handle game connections
+ */
+
 struct AcceptData {
 	GMainContext *context;
 	GSocketListener *listener;

src/networking.h

@@ -23,9 +23,29 @@
 
 #include "wmud_types.h"
 
+/**
+ * TELNET_IAC:
+ *
+ * Telnet IAC code
+ */
 #define TELNET_IAC '\xff'
+/**
+ * TELNET_WONT:
+ *
+ * Telnet WON'T code
+ */
 #define TELNET_WONT '\xfc'
+/**
+ * TELNET_WILL:
+ *
+ * Telnet WILL code
+ */
 #define TELNET_WILL '\xfb'
+/**
+ * TELNET_ECHO:
+ *
+ * Telnet ECHO code
+ */
 #define TELNET_ECHO '\x01'
 
 extern GSList *clients;

src/players.c

@@ -29,7 +29,16 @@
 #include "players.h"
 
 /**
- * @players: GSList of all loaded players. Stores #wmudPlayer structures.
+ * SECTION:player
+ * @short_description: Player database handling
+ *
+ * Functions to handle player database records
+ */
+
+/**
+ * players:
+ *
+ * GSList of all loaded players. Stores #wmudPlayer structures.
  */
 GSList *players = NULL;
 

src/wmud_types.h

@@ -22,6 +22,13 @@
 #include <glib.h>
 #include <gio/gio.h>
 
+/**
+ * SECTION:types
+ * @short_description: wMUD Data Types
+ * @title: wMUD's Data Types
+ *
+ */
+
 /**
  * wmudClientState:
  * @WMUD_CLIENT_STATE_FRESH: Client is newly connected. Waiting for a login
@@ -64,7 +71,7 @@ typedef enum {
  *     maintenance loop
  * @email: E-mail address of the player
  *
- * The <structname>wmudPlayer<structname> structure contains all information of
+ * The <structname>wmudPlayer</structname> structure contains all information of
  * a player.
  */
 typedef struct _wmudPlayer {
@@ -85,6 +92,8 @@ typedef struct _wmudPlayer {
  *     registration, so it should be always checked if the player is a saved
  *     database user
  * @bademail: indicates that the entered e-mail address is invalid
+ * @socket_source: the #GSource associated with the client socket
+ * @login_try_count: the failed login count of the client
  *
  * <structname>wmudClient</structname> contains all properties of a connected
  * game client.