README

   1 mp_doccer README
   2 ================
   3
   4  mp_doccer - A C source code documentation generator
   5  Copyright (C) 2001/2008 Angel Ortega <angel@triptico.com>
   6  Home Page: http://triptico.com/software/mp_doccer.html
   7
   8 This software is GPL. NO WARRANTY. See file 'COPYING' for details.
   9
  10 Description
  11 -----------
  12
  13 This is a tool that travels a bunch of C code files and extracts specially
  14 marked information to build documentation texts. It's similar to Javadoc, the
  15 Linux Kernel 2.4.x Documentation and gtkdoc, but simpler / faster / nicer.
  16
  17 mp_doccer expects to find comments inside the source code in the following
  18 manner:
  19
  20  /**
  21   * function_name - brief description
  22   * @arg1: optional argument 1
  23   * @arg2: optional argument 2 (many)
  24   *
  25   * Longer description than
  26   * can span many lines
  27   * [category]
  28   * [category]
  29   */
  30  type function_prototype(type)
  31  /** optional alternative synopsis line */
  32  /** another optional alternative synopsis line */
  33  {
  34
  35 for functions, or
  36
  37  /**
  38   * variable_name - brief description
  39   *
  40   * Longer description than
  41   * can span many lines
  42   * [category]
  43   * [category]
  44   */
  45  type variable_name;
  46
  47 for variables. Note that the format for functions and variables is exactly the
  48 same, as the arguments are optional. The synopsis is taken from the end of
  49 the comment until a { or ; is found, so it works equally for variables and
  50 functions.
  51
  52 The format is almost the same as the one used in the Linux Kernel 2.4.x
  53 Documentation. In fact, I thought the markup described there was clean and
  54 simple so I started using it; but after seeing that those tools needed a
  55 complete SGML toolkit, I decided to make my own (don't need no stinkin'
  56 SGML monster to build some crappy HTML files, thanks).
  57
  58 If you want to put a synopsis other than the function definition, you
  59 can add after it (but before the {) in succesive lines between the /** and
  60 */ markers.
  61
  62 You can also add categories to each entry by appending lines surrounded
  63 by square brackets. You can have none, one or more for each function or
  64 variable. If you include categories, an index by category will be
  65 created for you in the output documentation.
  66
  67 The arguments and return value can be decorated in the description and the
  68 alternative synopsis by prefixing it with a @ or %, respectively.
  69
  70 The Minimum Profit source code is documented with this tool; take a look at
  71 it if you want examples.
  72
  73 As of this version, there are four possible output formats:
  74
  75  * html: a tree of HTML files.
  76  * man: a bunch of man pages in troff(1) format.
  77  * localhelp: an executable sh script (localhelp.sh by default), that
  78    gives help about the string sent as a command line argument.
  79  * html1: all in one big HTML page.
  80  * grutatxt: all in one big file in Grutatxt format.
  81
  82 The `html' format is the default. For `html' and `man', the -o parameter
  83 must be an existing directory. For `localhelp', `html1' and `grutatxt',
  84 the output file name.
  85
  86 It's easy to use; just document your functions as described above and type
  87
  88     $ mp_doccer *.c -f html -o docdirectory --title="Your Program API"
  89
  90 or
  91     $ mp_doccer *.c -f man -o docdirectory --title="Your Program API"
  92
  93 or
  94     $ mp_doccer *.c -f localhelp -o myhelp.sh --title="Your Program API"
  95
  96 or
  97     $ mp_doccer *.c -f html1 -o yourapi --title="Your Program API"
  98
  99 or
 100     $ mp_doccer *.c -f grutatxt -o yourapi --title="Your Program API"
 101
 102 Cascading Style Sheet Classes
 103 -----------------------------
 104
 105 The following CSS classes are used when HTML output is used:
 106
 107  * funcname: A function name
 108  * funcarg: A function's arguments
 109  * funcret: A function's return value
 110  * funcsyn: A function synopsis
 111
 112 To Do
 113 -----
 114
 115  * The mp_doccer markup can also be used to document structs, so it should
 116    be a good idea to have mp_doccer support it (now it doesn't).
 117
 118 ---
 119 Angel Ortega <angel@triptico.com>