"Fossies" - the Fresh Open Source Software Archive

Member "mp_doccer-1.2.2/README" (5 Nov 2008, 3663 Bytes) of package /linux/privat/old/mp_doccer-1.2.2.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 mp_doccer README
    2 ================
    3 
    4  Minimum Profit Tools: mp_doccer
    5  Copyright (C) 2001/2005 Angel Ortega <angel@triptico.com>
    6  Home Page: http://www.triptico.com/software/mp.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 
   81 The 'html' format is the default. For 'html' and 'man', the -o parameter
   82 must be an existing directory. For 'localhelp' and 'html1', the file name
   83 of the executable sh script or HTML file.
   84 
   85 It's easy to use; just document your functions as described above and type
   86 
   87     $ mp_doccer *.c -f html -o docdirectory --title="Your Program API"
   88 
   89 or
   90     $ mp_doccer *.c -f man -o docdirectory --title="Your Program API"
   91 
   92 or
   93     $ mp_doccer *.c -f localhelp -o myhelp.sh --title="Your Program API"
   94 
   95 or
   96     $ mp_doccer *.c -f html1 -o yourapi --title="Your Program API"
   97 
   98 Cascading Style Sheet Classes
   99 -----------------------------
  100 
  101 The following CSS classes are used when HTML output is used:
  102 
  103  * funcname: A function name
  104  * funcarg: A function's arguments
  105  * funcret: A function's return value
  106  * funcsyn: A function synopsis
  107 
  108 To Do
  109 -----
  110 
  111  * The mp_doccer markup can also be used to document structs, so it should
  112    be a good idea to have mp_doccer support it (now it doesn't).
  113 
  114 ---
  115 Angel Ortega <angel@triptico.com>