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 backslashes 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,Markup extensions>>
  16   * <<xrefs,Cross referencing>>
  17   * <<symbols,Symbol formatting>>
  18 - <<extract,Header extraction>>
  19   * <<scomm,Stand-alone comments>>
  20   * <<defcomm,Definition comments>>
  21 - <<generics,Macro generics>>
  22   * <<geext,Generics extraction>>
  23   * <<gelink,Links to generics>>
  24
  25 [[markup]]
  26 Markup extensions
  27 -----------------
  28
  29 [[xrefs]]
  30 Cross referencing
  31 ~~~~~~~~~~~~~~~~~
  32 ASCIIDOC supports creating anchors with `\[[anchor-name]]` and links
  33 to them with `\<<anchor,caption>>`. The extension supports links to
  34 anchor in other files (`\\<<filename:anchor,caption>>`) or to other
  35 files (`\\<<filename:,caption>>`). The `filename` is without any suffix
  36 like `.txt` or `.html`, it is added to the link automatically. The caption
  37 is optional, if you omit it, some reasonable one will be guessed from
  38 the anchor name.
  39
  40 The links support linking to function descriptions (the anchors for
  41 them are generated automatically by <<extract,header extraction>>).
  42 Just write `\<<function(),caption>>` or
  43 `\\<<filename:function(),caption>>`.
  44
  45 [[symbols]]
  46 Symbol formatting
  47 ~~~~~~~~~~~~~~~~~
  48 If you talk about function parameter, prefix its name with `@`. It
  49 will be typeset in monospace italic font to mark it visually, like
  50 this: @parameter.
  51
  52 If a word is suffixed by parenthesis without a space (eg. word()), it
  53 is considered to be a function name and is typeset in monospace font.
  54
  55 You can prefix a function name by `@`, which makes it a link to that
  56 function (`\@function()` is equivalent to `\<<function()>>`).
  57
  58 If you write NULL anywhere, it is recognized and typeset in monospace.
  59
  60 [[extract]]
  61 Header extraction
  62 -----------------
  63 Line starting with two exclamation marks, followed by a filename, is a
  64 command to process source file. Special comments and commented
  65 declarations are extracted and included in the place of the command.
  66
  67 The command looks like this:
  68
  69   !!filename
  70
  71 [[scomm]]
  72 Stand-alone comments
  73 ~~~~~~~~~~~~~~~~~~~~
  74 C comments with tripled asterisks are extracted, the left side
  75 asterisk decoration is removed and the rest is put trough verbatim.
  76
  77 Single-line version looks like
  78
  79  /*** This will be put into documentation. ***/
  80
  81 If you need more than one line, use the same type of comment.
  82
  83  /***
  84   * This is part of documentation too.
  85   * But the asterisks on the left side aren't.
  86   ***/
  87
  88 [[defcomm]]
  89 Definition comments
  90 ~~~~~~~~~~~~~~~~~~~
  91 You can write comments documenting specific definition. Definition
  92 comment has the asterisks doubled. The multi-line version must be
  93 directly above the definition, the single-line on the same line right
  94 of the definition.
  95
  96  void function(int parameter);  /** This is a function. **/
  97
  98 or
  99
 100  /**
 101   * This is a complicated function.
 102   * It takes multiple lines to describe how useful it is.
 103   **/
 104  void function(int parameter);
 105
 106 Each such commented definition is taken and formatted, with the
 107 description attached. It also generates an anchor for the symbol name.
 108 The anchors look like `symboltype_symbolname`. The symbol types are
 109 these:
 110
 111 - `fun` for functions
 112 - `def` for preprocessor macro
 113 - `var` for variable
 114 - `struct` for structure
 115 - `enum` for enumeration
 116 - `type` for a type definition
 117
 118 There is a support for building a page with list of all symbols with
 119 links to them. Look into `ucw/doc/Makefile` to see how to request that.
 120
 121 [[generics]]
 122 Support for macro generics
 123 --------------------------
 124
 125 Some of the headers contain <<generic:,macro generics>>. Since the
 126 preprocessor macros look somewhat weird, the documentation extractor
 127 needs some help to understand them.
 128
 129 [[geext]]
 130 Extraction of generics
 131 ~~~~~~~~~~~~~~~~~~~~~~
 132
 133 When extracting info from some header, the extractor needs to know,
 134 which prefix macros are used in the source file, to distinguish them
 135 from function calls. To inform it about them, append a comma separated
 136 list of such macros to the extraction command, like this:
 137
 138   !!filename PREFIX_MACRO_ONE,PREFIX_MACRO_TWO
 139
 140 Then this will be correctly identified as a structure:
 141
 142   struct PREFIX_MACRO_ONE(struct_name) {
 143     content;
 144   };
 145
 146 [[gelink]]
 147 Links to generics
 148 ~~~~~~~~~~~~~~~~~
 149
 150 Since the anchors for them are generated in a complicated manner and
 151 typing them in plain-text would convert them back to the original,
 152 with real parenthesis, there is a special pattern to create the
 153 symbolname part of the anchor. It looks like:
 154
 155   _GENERIC_LINK_|PREFIX_MACRO|symbol_name|
 156
 157 So link to the above structure would look like:
 158
 159   <<struct__GENERIC_LINK_|PREFIX_MACRO_ONE|struct_name|,link text>>
 160
 161 However, this is implemented only in the included header files (if it
 162 is needed, it will be implemented in the top-level documentation files
 163 too).