gendoc.m4

   1 changequote(`«', `»')dnl
   2 define(«IFNBLANK», «ifelse(translit(««$1»», «
   3          »), «», «», «$2»)»)dnl
   4 define(«DECL_ARGLIST», «ifelse(«$#», «2», ««$1»», «dnl
   5 «$1», DECL_ARGLIST(shift(shift($@)))»)»)dnl
   6 ifelse(OUTPUT_MODE, «C», «dnl --------- C output
   7 define(«STRIP_TABS», «translit(««$1»», «        »)»)dnl
   8 define(«CHOP_FIRST», «translit(patsubst(translit(««««$1»»»», «
   9 », «  »), «^....    \(.*\)....$», «««\1»»»), «      », «
  10 »)»)dnl
  11 define(«CHOP_LAST»,
  12 «format(««%.*s»», regexp(translit(««$1»», «
  13 /», «/ »), «/*$»), «$1»)»)dnl
  14 define(«NORMALIZE», «CHOP_LAST(CHOP_FIRST(STRIP_TABS(«$1»)))»)dnl
  15 define(«COMMENT», «patsubst(patsubst(«««$1»»», «^\(.\)», « \1»), «^», «$2»)»)dnl
  16 define(«INDENT», «COMMENT(NORMALIZE(«$1»), « *»)»)dnl
  17 define(«INDENT_PARAM», «COMMENT(NORMALIZE(«$1»), « *      »)»)dnl
  18 define(«INDENT_PARAM_DOC», «COMMENT(NORMALIZE(«$1»), « *          »)»)dnl
  19 define(«INDENT_RETVAL_DOC», «COMMENT(NORMALIZE(«$1»), « * »)»)dnl
  20 define(«INDENT_MEMBER_DOC», «COMMENT(NORMALIZE(«$1»), «    *»)»)dnl
  21 define(«INDENT_MEMBER», «patsubst(NORMALIZE(««$1»»), «^[         ]*», «       »)»)dnl
  22 define(«DECL_ARG_TEXT», «ifelse(«$#», «1», «», «
  23 INDENT_PARAM(«$1»):
  24 INDENT_PARAM_DOC(«$2»)«»dnl
  25 DECL_ARG_TEXT(shift(shift($@)))»)»)dnl
  26 define(«PRINT_ARGS», «ifelse(«$2», «», «», «dnl
  27  *
  28  * Parameter(s):DECL_ARG_TEXT($@)»
  29 )»)dnl
  30 define(«DECLARE_FUNCTION», «dnl
  31 /*
  32  * «$1»(): «$2»
  33 IFNBLANK(«$3», «dnl
  34  *
  35 INDENT(«$3»)
  36 »)dnl
  37 PRINT_ARGS($4)dnl
  38 IFNBLANK(«$5», «dnl
  39  *
  40 INDENT(«$5»)
  41 »)dnl
  42 IFNBLANK(«$7», «dnl
  43  *
  44  * Return («$6»):
  45 INDENT_RETVAL_DOC(«$7»)
  46 »)dnl
  47 IFNBLANK(«$8», «dnl
  48  *
  49 INDENT(«$8»)
  50 »)dnl
  51  */
  52 «$6» «$1»(DECL_ARGLIST($4));dnl
  53 »)dnl
  54 define(«STATEMENT», «dnl
  55 /*
  56 INDENT(«$2»)
  57 IFNBLANK(«$3», «dnl
  58  *
  59 INDENT(«$3»)
  60 »)dnl
  61  */
  62 «$1»;»)dnl
  63 define(«COMPOUND_MEMBERS», «ifelse(«$#», «1», «»,
  64 «      /*
  65 INDENT_MEMBER_DOC(«$2»)
  66          */
  67 INDENT_MEMBER(«$1»);
  68 COMPOUND_MEMBERS(shift(shift($@)))»)»)dnl
  69 define(«DECLARE_COMPOUND», «dnl
  70 /*
  71  * «$2»
  72 IFNBLANK(«$3», «dnl
  73  *
  74 INDENT(«$3»)
  75 »)dnl
  76  */
  77 «$1» {
  78 COMPOUND_MEMBERS($4)dnl
  79 };dnl
  80 »)dnl
  81 define(«ENUM_MEMBERS», «ifelse(«$#», «1», «»,
  82 «      /*
  83 INDENT_MEMBER_DOC(«$2»)
  84          */
  85 INDENT_MEMBER(«$1»),
  86 ENUM_MEMBERS(shift(shift($@)))»)»)dnl
  87 define(«DECLARE_ENUM», «/* «$2» */
  88 IFNBLANK(«$3», «dnl
  89  *
  90 patsubst(«$3», «^\s*», « * »)
  91 »)dnl
  92 enum «$1» {
  93 ENUM_MEMBERS($4)dnl
  94 };dnl
  95 »)dnl
  96 define(«VERBATIM_C», «NORMALIZE(«$1»)»)dnl
  97 », OUTPUT_MODE, «HTML», «dnl --------- HTML output
  98         define(«LINK_COUNT», 0)dnl
  99         define(«FIXUP_LT», «patsubst(«$1», «<», «&lt;»)»)
 100         define(«FIXUP_GT», «patsubst(«$1», «>», «&gt;»)»)
 101         define(«FIXUP_AMPERSAND», «patsubst(«$1», «&», «&amp;»)»)
 102         define(«HANDLE_EMPTY_LINES», «patsubst(«$1», «^\s*$», «</p><p>»)»)
 103         define(«FIXUP_HTML», «FIXUP_AMPERSAND(FIXUP_LT(FIXUP_GT(««««$1»»»»)))»)
 104         define(«FORMAT_LIST_HTML», «ifelse(«$#», «1», «», «
 105                 IFNBLANK(«$2», «<li> <tt>«$1»</tt>: HANDLE_EMPTY_LINES(FIXUP_HTML(««$2»»)) </li>
 106                 FORMAT_LIST_HTML(shift(shift($@)))»)»
 107         )»)
 108         define(«ANCHOR», «
 109                 id="link_«»LINK_COUNT"
 110         »)
 111         define(«HREF», «
 112                 define(«LINK_COUNT», incr(LINK_COUNT))
 113                 <a href = "«#»link_«»LINK_COUNT"> «$1» </a>
 114         »)
 115         define(«DECLARE_FUNCTION», «
 116                 divert
 117                 <tr> <td> <tt> HREF(«$1()») </tt> </td> <td> «$2» </td> </tr>
 118                 divert(«1»)
 119                 <h2 ANCHOR()> <tt> «$6» «$1»(DECL_ARGLIST($4)) </tt> </h2>
 120                 <strong> FIXUP_HTML(«$2») </strong>
 121                 <p> HANDLE_EMPTY_LINES(FIXUP_HTML(««$3»»)) </p>
 122                 <ul> FORMAT_LIST_HTML($4) </ul>
 123                 <p> HANDLE_EMPTY_LINES(FIXUP_HTML(««$5»»)) </p>
 124                 IFNBLANK(«$7», «Return (<tt>«$6»</tt>):
 125                         <ul><li> FIXUP_HTML(«$7») </li></ul>»)
 126                 <p> HANDLE_EMPTY_LINES(FIXUP_HTML(««$8»»)) </p>
 127                 <hr>
 128         »)
 129         define(«STATEMENT», «
 130                 divert
 131                 <tr> <td> <tt> HREF(«$1») </tt> </td> <td> «$2» </td>
 132                 divert(«1»)
 133                 <h2 ANCHOR()> <tt> «$1» </tt> </h2>
 134                 <strong> FIXUP_HTML(«$2») </strong>
 135                 <p> HANDLE_EMPTY_LINES(FIXUP_HTML(««$3»»)) </p>
 136                 <hr>
 137         »)
 138         define(«DECLARE_COMPOUND», «
 139                 divert
 140                 <tr> <td> <tt> HREF(«$1») </tt> </td> <td> «$2» </td>
 141                 divert(«1»)
 142                 <h2 ANCHOR()> <tt> «$1» </tt> </h2>
 143                 <strong> FIXUP_HTML(«$2») </strong>
 144                 <p> HANDLE_EMPTY_LINES(FIXUP_HTML(««$3»»)) </p>
 145                 Members:
 146                 <ul> FORMAT_LIST_HTML($4) </ul>
 147                 <hr>
 148         »)
 149         define(«DECLARE_ENUM», «
 150                 divert
 151                 <tr> <td> <tt> HREF(«enum $1») </tt> </td> <td> «$2» </td>
 152                 divert(«1»)
 153                 <h2 ANCHOR()> <tt> enum «$1» </tt> </h2>
 154                 <strong> FIXUP_HTML(«$2») </strong>
 155                 <p> HANDLE_EMPTY_LINES(FIXUP_HTML(««$3»»)) </p>
 156                 Enumeration Constants:
 157                 <ul> FORMAT_LIST_HTML($4) </ul>
 158                 <hr>
 159         »)
 160         define(«VERBATIM_C»)
 161         divert(«1») </table> <hr> </div> divert
 162         <center> <h1> API Reference </h1> </center>
 163         <div class="toc"> <table>
 164 »)dnl
 165 ifdef(«EXAMPLES», «
 166 dnl     $1: name, $2: one-line summary, $3: prolog, $4: parameters,
 167 dnl     $5: parameter documentation, $6: return type, $7: return text,
 168 dnl     $8: epilog
 169 DECLARE_FUNCTION(
 170         «simple_func»,
 171         «This is the one-line summary.»,
 172         «This is the prolog.»,
 173         «
 174                 «int param1»,
 175                 «documentation of first parameter»,
 176
 177                 «char *param2»,
 178                 «documentation of second parameter»
 179         »,
 180         «This is the parameter documentation section.»,
 181
 182         «int»,
 183         «This is the documentation of the return value»,
 184         «This is the epilog.»
 185 )
 186
 187 DECLARE_FUNCTION(
 188         «complex_func»,
 189         «Example of a function which uses all features of gendoc»,
 190         «Prolog: The three free text sections (prolog, arg-doc and epilog) may
 191         all consist of several paragraphs, and each may contain multiple lines.
 192         Paragraphs are separated by lines containing only whitespace.
 193
 194         Formatting is kept intact, but lines are wrapped into C comments.»,
 195         «
 196                 «int par1»,
 197                 «The parameter list consists of any number of parameter/comment
 198                 pairs. The parameters are plain C code like the "int par1" above.
 199
 200                 The list must be quoted, and both the declaration and its
 201                 comment must also be quoted. Comments must not be empty.»,
 202
 203                 «int par2»,
 204                 «For the parameter documentation the same rules as for the free text
 205                 sections apply: Multiple paragraphs are possible, and each may spawn
 206                 multiple lines.»
 207
 208         »,
 209         «The par-doc section. It is printed after the parameter list but before
 210         the return value (if any).
 211
 212         It is supposed to describe the function or its parameters in more
 213         detail, possibly referring to one or more of the above parameters.
 214
 215         This function returns non-void, so this paragraph is followed by the
 216         return value documentation.»,
 217
 218         «int»,
 219         «Like the parameter/comment pairs, the return value consists of two parts:
 220         the return type and the documentation.
 221
 222         This return documentation consists of two paragraphs.»,
 223         «Finally, there is the (optional) epilog.
 224
 225         It might contain references to related documentation, for example a
 226         "see also" section.»
 227 )
 228
 229 DECLARE_FUNCTION(
 230         «dwim»,
 231         «Example of a function with no parameters and no return value.»,
 232         «This is the description. It could consist of several paragraphs.»,
 233
 234         «
 235                 «void»,
 236         »,
 237         «Par-doc: For functions with no parameters, the par-doc section
 238         is kind of pointless.»,
 239
 240         «void»,
 241         «»,
 242         «Epilog: For functions with no return value, the epilog directly
 243         follows the par-doc section.»,
 244 )
 245
 246 DECLARE_FUNCTION(
 247         «minimal_documented_function»,
 248         «This documentation conists of only the summary line.»,
 249         «»,
 250
 251         «
 252                 «void»,
 253         »,
 254         «»,
 255         «void»,
 256         «»,
 257         «»,
 258 )
 259
 260 dnl     $1: name, $2: one-line summary, $3: description, $4: members
 261 DECLARE_COMPOUND(
 262         «struct foo»,
 263         «summary: Illustrate the DECLARE_COMPOUND macro»,
 264         «description: The macro works for both structs and unions. The
 265         structure of the documentation is simpler than for functions because
 266         instead of three free-text sections (prolog, par-doc, epilog), it
 267         has only one: the description. Of course the description may spawn
 268         multiple paragraphs, each of which which may consist of multiple lines.
 269
 270         The member list is similar to the list of function parameters.»,
 271
 272         «
 273                 «float member1»,
 274                 «The description of the members may also spawn multiple paragraphs,
 275                 and each of them may spawn multiple lines.
 276
 277                 This description has two paragraphs.»,
 278
 279                 «float member2»,
 280                 «The documentation might be pretty short, though»
 281         »
 282 )
 283
 284 dnl     $1: name, $2: one-line summary, $3: description, $4: members
 285 DECLARE_ENUM(
 286         «example_enum»,
 287         «Summary: Illustrate the DECLARE_ENUM macro»,
 288         «Enumerations are similar to compounds in that they receive a one-line
 289         summary and an optional long description, The member list (paramter
 290         #4) is expected to be a list of identifier/comment pairs.»,
 291
 292         «
 293                 «ENUM_ID1»,
 294                 «comment 1»,
 295
 296                 «ENUM_ID2»,
 297                 «Comments can span multiple lines. Formatting is retained, but
 298                 leading and trailing newlines are stripped and leading tabs are
 299                 adjusted to make the C output look nice.»
 300         »
 301 )
 302
 303 dnl     $1: name, $2: one-line summary, $3 description
 304 STATEMENT(
 305         «extern int bar»,
 306         «Summary: Illustrate the STATMENT macro»,
 307         «If the header file contains simple statements, they can be documented
 308         with a one-line summary and an optional multi-paragraph description.
 309
 310         This is the second paragrapgh of the description.»
 311 )
 312
 313 STATEMENT(
 314         «struct opaque»,
 315         «Summary: A statement without a description»,
 316 )
 317 »)dnl