MXDOC

HTML documentation generator for C

This program parses C headers and source files reading comments of the form /** ... */ and outputs HTML documentation of the files. An example of the documentation generated is here.

News

• Version 2.6 (04/25/2007)
  • Removed the necessity for the typedef to be on the line immediately following the documentation since GNU Indent seems to do that to my typedef sometimes.
• Version 2.5 (04/20/2007)
  • Added global tag for globally accesible variables.
• Version 2.4 (11/04/2007)
  • Added _top_ tag for cleaner presentation of tagged documentation.
• Version 2.3 (24/01/2007)
  • Added possibility for tagged unattached comments to be placed at the top of the tag page. This is useful for summaries of the tags.
• Version 2.2 (01/10/2007)
  • Improved recognition of libraries.
  • Improved docs produced when only modules are found (no libraries).
  • Added tag page.
• Version 2.1 (01/06/2007)
  • Fixed handling of plain C comments and made documentation recognition code more robust.
  • Fixed some minor HTML 4.01 problems in the generated output.

Download

Why?

Other automatic documentation systems exist, such as Doxygen, GNU GLobal, or Natural Docs. All of these systems allow documentation to be embedded in the C source code so it's easy to keep code and comments properly synchronized. So there is no need to maintain separate source code and documentation and risk having them become unsyncronized. So what is special about MXDOC?

Advantages of MXDOC

• Completely free-standing with no installation, configuration or dependencies
• Easy to learn and implement
• Documentation output is valid HTML 4.01 with a simple layout
• Encourages modular programming
• Open source and GPL license encourages 'share-and-share-alike'

Disadvantages of MXDOC

• No configuration so it is not very powerful or flexible
• Not useful for source code exploration like Doxygen or GNU Global
• Function prototypes and arguments are not parsed so it is possible for comments and code to become unsynchronized
• Limited usefulness without a modular programming technique
• Not useful with programming languages other than C

How do I document using MXDOC?

There are several ways in which objects can be documented:

• typedef
  Typedefs are documented in the following way:

  /** This is a documented typedef */
  typedef ... {
      ...
      /** This is an member */
      int element1;
      ...
      int element2; /** This is another member */
      ....
  } name;

  Another possibility exists for simple typedefs:

  /** This is a documented typedef */
  typedef ... ;

  Typedef objects are associated with a 'type' tag.

• function
  Functions are documented in the following way:

  /** This is a documented function definition */
  void function_name(void)
  {
      ...
      /** This is added to the documentation for the function */
      ...
  }
  

  The opening brace must be the first character on the line. No blank lines may exist between the function name and the opeing brace or between the documentation comment and the function name.

  The initial comment is not mandatory and a function defined like:

  void function_name(void)
  {
      ...
      /** This is added to the documentation for the function */
      ...
  }
  

  will also be corrctly documented.

  Function declarations may also de documented:

  /** This is a documented function declaration */
  void function_name(void);
  

  Function objects are associed with a 'func' tag.

  If both the function declaration and definition are both documented then the documentation for both are combined into a single documented function.

• macro
  Macros are documented in the following way:

  /** This is a documented macro */
  #define documented_macro(a) (a)
  

  Macro objects are associed with a 'macro' tag.

• define
  Defines are documented in the following way:

  /** This is a documented define */
  #define FOO_MESSAGE "foo"
  

  Define objects are associed with a 'define' tag.

• module
  Modules are documented with /** ... */ constructs that are not associated with any object. This can be achieved by having the /** ... */ construct followed by an empty line.

  Equivalently, the tag 'module' can also be used, i.e. /**module ... */. Associated documentation is added to the top level documentation for the current library.

• library
  Libraries are documented with tag 'library'. Associated documentation is added to the top level documentation for the current library.

• mainpage
  Documentation having the tag 'mainpage' will be added to the top-level main documentation page.

• global
  Documentation having the tag 'global' will be added to the global tag page.

What are tags?

Tags can be user defined. A useful tag is the 'todo' tag which can collect documentation in a central 'todo' page. An example of a user generated tags is:

/**todo,fixme This function needs to be completed */
void unfinished function(void) 
{
}

A special tag _top_ exists to force the associated text to the top of the tag page. This is useful for summaries of the tags.

Short-form documentation

What is modular programing?

Modular programming in C is a method of organizing header files and source code so that application programming interfaces (APIs) are sensible and useful. There are 3 different kinds of C modules:

• Just header file
  This kind of module usually just contains simple defines.

• A header file and a corresponding C source file
  This kind of module is useful for collections of small numbers of functions.

• A header file and a corresponding sub-directory with a number of C source files
  This kind of module is useful for more complex collections of functions.