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 or on a line before.
  95
  96  void function(int parameter);  /** This is a function. **/
  97
  98 or
  99
 100  /** This is a function. **/
 101  void function(int parameter);
 102
 103 or
 104
 105  /**
 106   * This is a complicated function.
 107   * It takes multiple lines to describe how useful it is.
 108   **/
 109  void function(int parameter);
 110
 111 Each such commented definition is taken and formatted, with the
 112 description attached. It also generates an anchor for the symbol name.
 113 The anchors look like `symboltype_symbolname`. The symbol types are
 114 these:
 115
 116 - `fun` for functions
 117 - `def` for preprocessor macro
 118 - `var` for variable
 119 - `struct` for structure
 120 - `enum` for enumeration
 121 - `type` for a type definition
 122
 123 There is a support for building a page with list of all symbols with
 124 links to them. Look into `ucw/doc/Makefile` to see how to request that.
 125
 126 [[generics]]
 127 Support for macro generics
 128 --------------------------
 129
 130 Some of the headers contain <<generic:,macro generics>>. Since the
 131 preprocessor macros look somewhat weird, the documentation extractor
 132 needs some help to understand them.
 133
 134 [[geext]]
 135 Extraction of generics
 136 ~~~~~~~~~~~~~~~~~~~~~~
 137
 138 When extracting info from some header, the extractor needs to know,
 139 which prefix macros are used in the source file, to distinguish them
 140 from function calls. To inform it about them, append a comma separated
 141 list of such macros to the extraction command, like this:
 142
 143   !!filename PREFIX_MACRO_ONE,PREFIX_MACRO_TWO
 144
 145 Then this will be correctly identified as a structure:
 146
 147   struct PREFIX_MACRO_ONE(struct_name) {
 148     content;
 149   };
 150
 151 [[gelink]]
 152 Links to generics
 153 ~~~~~~~~~~~~~~~~~
 154
 155 Since the anchors for them are generated in a complicated manner and
 156 typing them in plain-text would convert them back to the original,
 157 with real parenthesis, there is a special pattern to create the
 158 symbolname part of the anchor. It looks like:
 159
 160   _GENERIC_LINK_|PREFIX_MACRO|symbol_name|
 161
 162 So link to the above structure would look like:
 163
 164   <<struct__GENERIC_LINK_|PREFIX_MACRO_ONE|struct_name|,link text>>
 165
 166 However, this is implemented only in the included header files (if it
 167 is needed, it will be implemented in the top-level documentation files
 168 too).