tbaMUD Continued development of the CircleMUD core

In upcoming releases of tbaMUD you might notice an increase in source code documentation. If you have Doxygen installed on your system, you will also be able to create a hyper linked, cross referenced manual anytime you wish.

If you haven't used it before, Doxygen is a free, open source program that will read through specially formatted comments in source code, cross link functions, data structures and global variables, and even create intricate call graphs with the Graphviz package (also free and open source).

The Doxygen site explains everything you would need to know about running the program. As a developer of tbaMUD, you don't ever have to install Doxygen or Graphviz, let alone use them, if you don't want to. If you do wish to use them, we have included configuration files that have been altered to work with the function macros found in the source code. All you'll need to do is download and install Doxygen, and Graphviz if you want to create the call graphs.

The source code itself will only look slightly different. The following is a fictitious example showing the formatted comments and keywords you're likely to find in the source.


/**
* @file test.c
* Any comment that begins with a slash-star-star followed by white space
* is the beginning of a comment that can be cross referenced. No other
* special formatting is needed to get the comment recognized. Internal to
* any comment, special keywords can be used. Since this is the file header
* we use the 'at'file keyword followed by the name of the file, in this case
* test.c. Any notes and annotations made inside of the comments are
* included in the generated documentation.
*/


/** Most things can be marked for cross reference */
#include "conf.h"


/** When a comment begins with /** doxygen usually uses it to comment
* whatever immediately follows, in this case the test structure. */
struct test
{
/** Internal elements can be commented either above */
int i; /**< Or immediately following, with the addition of a '<' */
};


/** Functions will use more special keywords, on average, than any other
* piece of code.
* @pre This tag will only be used sometimes. It marks any pre-condition that
* should be met before using this function that is not obvious.
* @post This tag marks any post-condition caused by this function. Often
* the description of the parameters and return value will suffice for the
* post condition.
* @todo This tag may sometimes be included to mark things that should be
* done. The advantage of using this tag is that doxygen will associate this
* tag with the associated function, variable, etc. All todo tags
* will be indexed in a single location in the final documentation.
* @deprecated This tag marks a function or variable that is still in use but is
* currently being phased out. Like the todo tag, the deprecated tag gets
* associated with whatever it is attached to and indexed in its own page.
* @param arg1 There is one param tag for each function parameter. The
* tag is immediately followed by the parameter name, followed by information
* about this parameter.
* @param[in] arg2 If a parameter is specifically designed to pass in a value,
* the param tag might be affixed with [in].
* @param[out] arg3 If a parameter is specifically designed to hold the results
* of a function, it can be be affixed with [out].
* @retval int Used if the function has a return value, the type returned
* follows the tag, and a description of the return value follows that.
*/
int do_nothing(int arg1, int *arg2, int *arg3)
{
return 1;
}