1 changequote(`«', `»')dnl
2 define(«IFNBLANK», «ifelse(translit(««$1»», «
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»»»), « », «
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», «», «
24 INDENT_PARAM_DOC(«$2»)«»dnl
25 DECL_ARG_TEXT(shift(shift($@)))»)»)dnl
26 define(«PRINT_ARGS», «ifelse(«$2», «», «», «dnl
28 * Parameter(s):DECL_ARG_TEXT($@)»
30 define(«DECLARE_FUNCTION», «dnl
45 INDENT_RETVAL_DOC(«$7»)
52 «$6» «$1»(DECL_ARGLIST($4));dnl
54 define(«STATEMENT», «dnl
63 define(«COMPOUND_MEMBERS», «ifelse(«$#», «1», «»,
65 INDENT_MEMBER_DOC(«$2»)
68 COMPOUND_MEMBERS(shift(shift($@)))»)»)dnl
69 define(«DECLARE_COMPOUND», «dnl
78 COMPOUND_MEMBERS($4)dnl
81 define(«ENUM_MEMBERS», «ifelse(«$#», «1», «»,
83 INDENT_MEMBER_DOC(«$2»)
86 ENUM_MEMBERS(shift(shift($@)))»)»)dnl
87 define(«DECLARE_ENUM», «/* «$2» */
90 patsubst(«$3», «^\s*», « * »)
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», «<», «<»)»)
100 define(«FIXUP_GT», «patsubst(«$1», «>», «>»)»)
101 define(«FIXUP_AMPERSAND», «patsubst(«$1», «&», «&»)»)
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($@)))»)»
109 id="link_«»LINK_COUNT"
112 define(«LINK_COUNT», incr(LINK_COUNT))
113 <a href = "«#»link_«»LINK_COUNT"> «$1» </a>
115 define(«DECLARE_FUNCTION», «
117 <tr> <td> <tt> HREF(«$1()») </tt> </td> <td> «$2» </td> </tr>
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>
129 define(«STATEMENT», «
131 <tr> <td> <tt> HREF(«$1») </tt> </td> <td> «$2» </td>
133 <h2 ANCHOR()> <tt> «$1» </tt> </h2>
134 <strong> FIXUP_HTML(«$2») </strong>
135 <p> HANDLE_EMPTY_LINES(FIXUP_HTML(««$3»»)) </p>
138 define(«DECLARE_COMPOUND», «
140 <tr> <td> <tt> HREF(«$1») </tt> </td> <td> «$2» </td>
142 <h2 ANCHOR()> <tt> «$1» </tt> </h2>
143 <strong> FIXUP_HTML(«$2») </strong>
144 <p> HANDLE_EMPTY_LINES(FIXUP_HTML(««$3»»)) </p>
146 <ul> FORMAT_LIST_HTML($4) </ul>
149 define(«DECLARE_ENUM», «
151 <tr> <td> <tt> HREF(«enum $1») </tt> </td> <td> «$2» </td>
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>
161 divert(«1») </table> <hr> </div> divert
162 <center> <h1> API Reference </h1> </center>
163 <div class="toc"> <table>
166 dnl $1: name, $2: one-line summary, $3: prolog, $4: parameters,
167 dnl $5: parameter documentation, $6: return type, $7: return text,
171 «This is the one-line summary.»,
172 «This is the prolog.»,
175 «documentation of first parameter»,
178 «documentation of second parameter»
180 «This is the parameter documentation section.»,
183 «This is the documentation of the return value»,
184 «This is the epilog.»
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.
194 Formatting is kept intact, but lines are wrapped into C comments.»,
197 «The parameter list consists of any number of parameter/comment
198 pairs. The parameters are plain C code like the "int par1" above.
200 The list must be quoted, and both the declaration and its
201 comment must also be quoted. Comments must not be empty.»,
204 «For the parameter documentation the same rules as for the free text
205 sections apply: Multiple paragraphs are possible, and each may spawn
209 «The par-doc section. It is printed after the parameter list but before
210 the return value (if any).
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.
215 This function returns non-void, so this paragraph is followed by the
216 return value documentation.»,
219 «Like the parameter/comment pairs, the return value consists of two parts:
220 the return type and the documentation.
222 This return documentation consists of two paragraphs.»,
223 «Finally, there is the (optional) epilog.
225 It might contain references to related documentation, for example a
231 «Example of a function with no parameters and no return value.»,
232 «This is the description. It could consist of several paragraphs.»,
237 «Par-doc: For functions with no parameters, the par-doc section
238 is kind of pointless.»,
242 «Epilog: For functions with no return value, the epilog directly
243 follows the par-doc section.»,
247 «minimal_documented_function»,
248 «This documentation conists of only the summary line.»,
260 dnl $1: name, $2: one-line summary, $3: description, $4: members
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.
270 The member list is similar to the list of function parameters.»,
274 «The description of the members may also spawn multiple paragraphs,
275 and each of them may spawn multiple lines.
277 This description has two paragraphs.»,
280 «The documentation might be pretty short, though»
284 dnl $1: name, $2: one-line summary, $3: description, $4: members
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.»,
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.»
303 dnl $1: name, $2: one-line summary, $3 description
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.
310 This is the second paragrapgh of the description.»
315 «Summary: A statement without a description»,