ucw/doc/docsys.txt

   1 The documentation system
   2 ========================
   3
   4 ////
   5 Warning: if you read this file in plain-text, keep in mind the markup
   6 had to be escaped to show in the result as the thing you should type.
   7 You should ignore all backspaces here, or better, read the html
   8 version.
   9 ////
  10
  11 The ucw documentation system is based on the
  12 http://www.methods.co.nz/asciidoc/[ASCIIDOC] documentation formatter.
  13 It supports all it's markup, but it was extended slightly.
  14
  15 [[markup]]
  16 Markup extensions
  17 -----------------
  18
  19 [[xrefs]]
  20 Cross referencing
  21 ~~~~~~~~~~~~~~~~~
  22 ASCIIDOC supports creating anchors with `\[[anchor-name]]` and links
  23 to them with `\<<anchor,caption>>`. The extension supports links to
  24 anchor in other files (`\\<<filename:anchor,caption>>`) or to other
  25 files (`\\<<filename:,caption>>`). The `filename` is without any suffix
  26 like `.txt` or `.html`, it is added to the link automatically. The caption
  27 is optional, if you omit it, some reasonable one will be guessed from
  28 the anchor name.
  29
  30 The links support linking to function descriptions (the anchors for
  31 them are generated automatically by <<extract,header extraction>>).
  32 Just write `\<<function(),caption>>` or
  33 `\\<<filename:function(),caption>>`.
  34
  35 [[symbols]]
  36 Symbol formatting
  37 ~~~~~~~~~~~~~~~~~
  38 If you talk about function parameter, prefix its name with `@`. It
  39 will be typeset in monospace italic font to mark it visually, like
  40 this: @parameter.
  41
  42 If a word is suffixed by parenthesis without a space (eg. word()), it
  43 is considered to be a function name and is typeset in monospace font.
  44
  45 You can prefix a function name by `@`, which makes it a link to that
  46 function (`\@function()` is equivalent to `\<<function()>>`).
  47
  48 If you write NULL anywhere, it is recognized and typeset in monospace.
  49
  50 [[extract]]
  51 Header extraction
  52 -----------------
  53 Line starting with two exclamation marks, followed by a filename, is a
  54 command to process source file. Special comments and commented
  55 declarations are extracted and included in the place of the command.
  56
  57 The command looks like this:
  58
  59   !!filename
  60
  61 [[scomm]]
  62 Stand-alone comments
  63 ~~~~~~~~~~~~~~~~~~~~
  64 C comments with tripled asterisks are extracted, the left side
  65 asterisk decoration is removed and the rest is put trough verbatim.
  66
  67 Single-line version looks like
  68
  69  /*** This will be put into documentation. ***/
  70
  71 If you need more than one line, use the same type of comment.
  72
  73  /***
  74   * This is part of documentation too.
  75   * But the asterisks on the left side aren't.
  76   ***/
  77
  78 [[defcomm]]
  79 Definition comments
  80 ~~~~~~~~~~~~~~~~~~~
  81 You can write comments documenting specific definition. Definition
  82 comment has the asterisks doubled. The multi-line version must be
  83 directly above the definition, the single-line on the same line right
  84 of the definition.
  85
  86  void function(int parameter);  /** This is a function. **/
  87
  88 or
  89
  90  /**
  91   * This is a complicated function.
  92   * It takes multiple lines to describe how useful it is.
  93   **/
  94  void function(int parameter);
  95
  96 Each such commented definition is taken and formatted, with the
  97 description attached. It also generates an anchor for the symbol name.
  98 The anchors look like `symboltype_symbolname`. The symbol types are
  99 these:
 100
 101 - `fun` for functions
 102 - `def` for preprocessor macro
 103 - `var` for variable
 104 - `struct` for structure
 105 - `enum` for enumeration
 106 - `type` for a type definition
 107
 108 There is a support for building a page with list of all symbols with
 109 links to them. Look into `ucw/doc/Makefile` to see how to request that.