[Package Index | Mudlib Index | Effect Index]

File /obj/handlers/autodoc/autodoc_handler.c

Documentation system for removing documentation from source files.

The documentation will be created in the directory /doc/autodoc. Extra documentation should be placed into the other help directories and will be accessed via the help system. The html documentation will be placed into the /www/autodoc directory. The files in theses directories will be named with the '/'s replaced with '.'s. ie: /obj/handlers/room_handler.c would be in the file /doc/autodoc/obj.handlers.room_handler.c and /www/autodoc/obj.handlers.room_handler.c.shtml. An index of the methods and object names will be generated from the input files and linked into the help system. An alphabetical index will also be produced that is linked to the html stuff.

The first comment which follows the comment format below and occurs right before a function will be used as the documentation for that function. The comment must start with two '*'s to distinguish it from a normal comment. A special tag at the start of one of the first comments in the file will signify that it is a comment for the class.

Only comments before a real function declaration will be used, comments before a predeclaration will be ignored.

Any function which is not declared as private and does not have the @ignore tag in its description will be placed into the resulting documentation file. This will be done even if no comment was found.

In the text part of the comment the main section is a free form documentation, it is merely a description of the whole function. After this several tags can be added to the comment which allows other things to be documented. All the text after the tag is taken as part of that tags information. The main tag should never actually be used, it is implied as being the tag associated with the first section of comment.

HTML tags will be used in the comments to allow certain things to happen. The tags 'p', 'b', 'i', 'code', 'ul', 'ol', 'dl', 'dd', 'dt', 'pre' and 'li' will be supported.

The sequences '/', '\' and '\<' will be processed by the comment handling code so that they do not get placed into the output code.

White space is ignored... Both html and dw nroff format files will be created from the documentation maker.

The supported tags are:

@param

Specify the parameter and what it does. This should be one short sentance only. There needs to be one of these for every parameter, the first word of the sentance is the name of the paramater and the rest is the descrption. There should be no full stop on the end of the sentance.

@member

This is used with classes and defines the members of the class. The definition is the same as for the @param element above.

@return

Specify what the return value is. This should be one short sentance only. Theres should only be one of these in every function. There should be no full stop on the end of the sentance.

@see

Specify an object or function to see. The format must be one of:

object_name
@see /global/new_parse
function_name()
@see frog()
object_name->function_name()
@see /global/new_parse->add_command()
efun::name()
@see efun::sort_array()
help::name
@see help::effects

@ignore

Do not document this function, the whole comment is ignored.

@main

The main documentation section.

@classification

Used in the effects files to classifiy the effect. So a tree of the classifications can be derived.

@index

Adds in a new index refernece on this name. This should be one word only.

@change

Placed in the class documentation to reference a change list. First line after the tag is the date and the author and then follows a description of the change.

@example

If you wish to embed an example in the code.

@started

When the file was started.

@author

The author of the file.

The output format will look something like the API documentation for java. If you have not seen this before, go to http://www.javasoft.com and look in the JDK and then the API section.

Comment format:

/**
 *  
 *    ..
 *  
 *
 */

ie: it starts with a /** and ends with a */ on a line by themselves and every intervening line has a * at the start. By using a \ you can make characters escaped. This means they are not processed by the internal system, so to make a end comment appear inside a the text you go : */

See also:
/obj/handlers/autodoc/autodoc_file.c, /obj/handlers/autodoc/autodoc_nroff.c and /obj/handlers/autodoc/autodoc_html.c

Written by Pinkfish

Started Tue Oct 28 13:25:09 EST 1997

Example

inherit "/std/object";

/**
 *   This class is a nice shade of blue and allows all other shades of
 *   green and yellow to mix well.
 * @see yellow
 * @see blue
 * @change 12/3/97 Pinkfish
 *    Pushed some of the yellow stuff down a hole and ate a bagel.
 */

/**
 * This method mixes the green in with our blue.
 * @param  green   the green object to mix.
 */
void mixGreen(object green) {
  /* Something wild and exciting! */
} /* mixGreen() */

/**
 * This method mixes the yellow in with our blue.
 * @param  yellow the yellow object to mix.
 * @return returns a TRUE or FALSE depending on if the mix succeeded.
 * @example
 *   mixYellow(12);
 */
int mixYellow(object yellow) {
} /* mixYellow() */

Includes

This class includes the following files /include/autodoc.h

Method index

add_file(string)
Adds a file into the list of files to process for autodocumentation.
create_index_1(int)
create_index_2(int)
is_autodoc_file(string)
This method tells us if the file is currently in the autodoc set.
query_files()
Returns the list of files we are current processing.
query_help_map()
Returns the help mapping.
query_help_on(string, string)
This method returns the file name of the help for the specified function in the specified file.
query_summary_map()
Retuirns the mapping of file names to a summary.
recreate_documentation(string)
Recreate documentation for one file immediately.
recreate_indexes()
Regenerate the index files.
remove_file(string)
Removes a file from the list of files to be processed for autodocumentation.

Public Functions

These are functions that everyone can access.

add_file int add_file(string fname)

Adds a file into the list of files to process for autodocumentation. This file will be processed every time around in the autodocumentation loop to check to see if it has been changed and the results will be placed into the index. It automaticly calls recreate_documentation in random(60) seconds.

Parameters:
fname - the name of the file to add

Returns:
1 if the add succeeds, 0 otherwise.

See also:
recreate_documentation()

create_index_1 void create_index_1(int i)

create_index_2 void create_index_2(int i)

is_autodoc_file int is_autodoc_file(string name)

This method tells us if the file is currently in the autodoc set.

Returns:
1 if the file is found, 0 if not

query_files string * query_files()

Returns the list of files we are current processing.

Returns:
an array of strings being the file names

query_help_map mapping query_help_map()

Returns the help mapping. This is the mapping from function names to files. Each element in the mapping referes to an array of file names which contain the function or define.

Returns:
a mapping of arrays of files

query_help_on string query_help_on(string file, string func)

This method returns the file name of the help for the specified function in the specified file.

Parameters:
file - the file name to find the help in
func - the function to look for help on in the file

Returns:
the full path to the help file, 0 if it does not exist

query_summary_map mapping query_summary_map()

Retuirns the mapping of file names to a summary. This is only valid during the index creation cycle of the documentation generation system. It is used to create a more useful index page.

Returns:
the mapping of file names to summarys

recreate_documentation int recreate_documentation(string fname)

Recreate documentation for one file immediately. This does not update the index, it merely creates the base files for this file. It does it at a random delay of up to 30 seconds.

Parameters:
fname - the file name to update

recreate_indexes void recreate_indexes()

Regenerate the index files.

remove_file int remove_file(string fname)

Removes a file from the list of files to be processed for autodocumentation.

Parameters:
fname - the name of the file to remove

Returns:
1 if the remove succeeds, 0 otherwise.