diff --git a/.gitignore b/.gitignore index 246a272..feaac45 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,5 @@ stamp-h1 *.db *.anjuta tags +gtk-doc.make +m4 diff --git a/Makefile.am b/Makefile.am index af437a6..3477bd2 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1 +1,2 @@ -SUBDIRS = src +SUBDIRS = src docs/reference/wmud +DISTCHECK_CONFIGURE_FLAGS = --enable-gtk-doc diff --git a/autogen.sh b/autogen.sh index 2202e61..7b47e8f 100755 --- a/autogen.sh +++ b/autogen.sh @@ -1,6 +1,9 @@ #! /bin/sh -autoheader -aclocal -autoconf -automake --add-missing --copy +mkdir m4 &> /dev/null +gtkdocize || exit 1 +autoheader || exit 1 +aclocal || exit 1 +autoconf || exit 1 +automake --add-missing --copy || exit 1 + diff --git a/configure.ac b/configure.ac index 5f0868e..58e6e67 100644 --- a/configure.ac +++ b/configure.ac @@ -1,6 +1,7 @@ AC_INIT([wMUD], [0.1.0]) AC_CONFIG_HEADER([config.h]) AC_CONFIG_SRCDIR([configure.ac]) +AC_CONFIG_MACRO_DIR([m4]) AM_INIT_AUTOMAKE([wMUD], [0.1.0]) @@ -21,6 +22,12 @@ if test "$enable_debug" = "yes"; then AC_DEFINE([DEBUG], [1], [Define to compile with debugging support]) fi +m4_ifdef([GTK_DOC_CHECK], [ +GTK_DOC_CHECK([1.14], [--flavour no-tmpl]) +],[ +AM_CONDITIONAL([ENABLE_GTK_DOC], false) +]) + AC_ARG_ENABLE([memcached], AS_HELP_STRING([--disable-memcached], [Disable Memcached support (default: enabled)]), [], [enable_memcached=yes]) AM_CONDITIONAL([ENABLE_MEMCACHED], [test "$enable_memcached" = "yes"]) if test "$enable_memcached" = "yes"; then @@ -36,4 +43,4 @@ PKG_CHECK_MODULES([GLIB], glib-2.0) PKG_CHECK_MODULES([GTHREAD], gthread-2.0) PKG_CHECK_MODULES([SQLITE3], sqlite3) -AC_OUTPUT(Makefile src/Makefile) +AC_OUTPUT(Makefile src/Makefile docs/reference/wmud/Makefile) diff --git a/docs/reference/wmud/.gitignore b/docs/reference/wmud/.gitignore new file mode 100644 index 0000000..d2a0c13 --- /dev/null +++ b/docs/reference/wmud/.gitignore @@ -0,0 +1,14 @@ +*.stamp +*.args +*.hierarchy +*.interfaces +*.prerequisites +*.signals +*-decl-list.txt +*-decl.txt +*-overrides.txt +*-undeclared.txt +*-undocumented.txt +*-unused.txt +html +xml diff --git a/docs/reference/wmud/Makefile.am b/docs/reference/wmud/Makefile.am new file mode 100644 index 0000000..d9105e3 --- /dev/null +++ b/docs/reference/wmud/Makefile.am @@ -0,0 +1,105 @@ +## Process this file with automake to produce Makefile.in + +# We require automake 1.6 at least. +AUTOMAKE_OPTIONS = 1.6 + +# This is a blank Makefile.am for using gtk-doc. +# Copy this to your project's API docs directory and modify the variables to +# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples +# of using the various options. + +# The name of the module, e.g. 'glib'. +DOC_MODULE=wmud + +# Uncomment for versioned docs and specify the version of the module, e.g. '2'. +#DOC_MODULE_VERSION=2 + + +# The top-level SGML file. You can change this if you want to. +DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml + +# Directories containing the source code. +# gtk-doc will search all .c and .h files beneath these paths +# for inline comments documenting functions and macros. +# e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk +DOC_SOURCE_DIR=$(top_srcdir)/src + +# Extra options to pass to gtkdoc-scangobj. Not normally needed. +SCANGOBJ_OPTIONS= + +# Extra options to supply to gtkdoc-scan. +# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" +SCAN_OPTIONS= + +# Extra options to supply to gtkdoc-mkdb. +# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml +MKDB_OPTIONS=--xml-mode --output-format=xml + +# Extra options to supply to gtkdoc-mktmpl +# e.g. MKTMPL_OPTIONS=--only-section-tmpl +MKTMPL_OPTIONS= + +# Extra options to supply to gtkdoc-mkhtml +MKHTML_OPTIONS= + +# Extra options to supply to gtkdoc-fixref. Not normally needed. +# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html +FIXXREF_OPTIONS= + +# Used for dependencies. The docs will be rebuilt if any of these change. +# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h +# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c +HFILE_GLOB= +CFILE_GLOB= + +# Extra header to include when scanning, which are not under DOC_SOURCE_DIR +# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h +EXTRA_HFILES= + +# Header files or dirs to ignore when scanning. Use base file/dir names +# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code +IGNORE_HFILES= + +# Images to copy into HTML directory. +# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png +HTML_IMAGES= + +# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). +# e.g. content_files=running.sgml building.sgml changes-2.0.sgml +content_files= + +# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded +# These files must be listed here *and* in content_files +# e.g. expand_content_files=running.sgml +expand_content_files= + +# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. +# Only needed if you are using gtkdoc-scangobj to dynamically query widget +# signals and properties. +# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS) +# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib) +GTKDOC_CFLAGS= +GTKDOC_LIBS= + +# This includes the standard gtk-doc make rules, copied by gtkdocize. +include $(top_srcdir)/gtk-doc.make + +# Other files to distribute +# e.g. EXTRA_DIST += version.xml.in +EXTRA_DIST += + +# Files not to distribute +# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types +# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt +#DISTCLEANFILES += + +# Comment this out if you want 'make check' to test you doc status +# and run some sanity checks +if ENABLE_GTK_DOC +TESTS_ENVIRONMENT = cd $(srcdir) && \ + DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ + SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir) +#TESTS = $(GTKDOC_CHECK) +endif + +-include $(top_srcdir)/git.mk diff --git a/docs/reference/wmud/wmud-docs.sgml b/docs/reference/wmud/wmud-docs.sgml new file mode 100644 index 0000000..9506fb8 --- /dev/null +++ b/docs/reference/wmud/wmud-docs.sgml @@ -0,0 +1,41 @@ + + +]> + + + wmud Reference Manual + + for wMUD 0.1. + The latest version of this documentation can be found on-line at + http://w00d5t0ck.info/wmud/. + + + + + wMUD hackers' guide + + + + + + + + + + Object Hierarchy + + + + API Index + + + + Index of deprecated API + + + + + diff --git a/docs/reference/wmud/wmud-sections.txt b/docs/reference/wmud/wmud-sections.txt new file mode 100644 index 0000000..43939f4 --- /dev/null +++ b/docs/reference/wmud/wmud-sections.txt @@ -0,0 +1,56 @@ +
+Data types +types +wmudClientState +wmudClient +wmudPlayer +
+ +
+Utilities and uncategorized functions +utils +random_number +wmud_random_string +
+ +
+Networking +networking +TELNET_IAC +TELNET_WILL +TELNET_WONT +TELNET_ECHO +clients +wmud_networking_init +wmud_client_send +
+ +
+Command interpreter +interpreter +wmudCommandFunc +wmudCommand +WMUD_COMMAND +wmud_interpret_game_command +
+ +
+Database handling +db +WMUD_DB_ERROR +wmudDbError +wmud_db_init +wmud_db_players_load +wmud_db_save_player +
+ +
+Player handling +player +players +wmud_player_dup +wmud_player_free +wmud_player_exists +wmud_player_auth +
+ diff --git a/src/db.c b/src/db.c index 4d91b9d..0fd3614 100644 --- a/src/db.c +++ b/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. * diff --git a/src/interpreter.c b/src/interpreter.c index 6fd49b5..d2a2d22 100644 --- a/src/interpreter.c +++ b/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[] = { diff --git a/src/main.c b/src/main.c index 6d71d16..209eb62 100644 --- a/src/main.c +++ b/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; /** diff --git a/src/networking.c b/src/networking.c index daeb496..e3e8a50 100644 --- a/src/networking.c +++ b/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; diff --git a/src/networking.h b/src/networking.h index 874c4d1..663540e 100644 --- a/src/networking.h +++ b/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; diff --git a/src/players.c b/src/players.c index 51a4495..8841abb 100644 --- a/src/players.c +++ b/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; diff --git a/src/wmud_types.h b/src/wmud_types.h index d6200c1..d878573 100644 --- a/src/wmud_types.h +++ b/src/wmud_types.h @@ -22,6 +22,13 @@ #include #include +/** + * 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 wmudPlayer structure contains all information of + * The wmudPlayer 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 * * wmudClient contains all properties of a connected * game client.