changequote(`«', `»')dnl
define(«IFNBLANK», «ifelse(translit(««$1»», «
»), «», «», «$2»)»)dnl
define(«DECL_ARGLIST», «ifelse(«$#», «2», ««$1»», «dnl
«$1», DECL_ARGLIST(shift(shift($@)))»)»)dnl
ifelse(OUTPUT_MODE, «C», «dnl --------- C output
define(«STRIP_TABS», «translit(««$1»», « »)»)dnl
define(«CHOP_FIRST», «translit(patsubst(translit(««««$1»»»», «
», « »), «^.... \(.*\)....$», «««\1»»»), « », «
»)»)dnl
define(«CHOP_LAST»,
«format(««%.*s»», regexp(translit(««$1»», «
/», «/ »), «/*$»), «$1»)»)dnl
define(«NORMALIZE», «CHOP_LAST(CHOP_FIRST(STRIP_TABS(«$1»)))»)dnl
define(«COMMENT», «patsubst(patsubst(«««$1»»», «^\(.\)», « \1»), «^», «$2»)»)dnl
define(«INDENT», «COMMENT(NORMALIZE(«$1»), « *»)»)dnl
define(«INDENT_PARAM», «COMMENT(NORMALIZE(«$1»), « * »)»)dnl
define(«INDENT_PARAM_DOC», «COMMENT(NORMALIZE(«$1»), « * »)»)dnl
define(«INDENT_RETVAL_DOC», «COMMENT(NORMALIZE(«$1»), « * »)»)dnl
define(«INDENT_MEMBER_DOC», «COMMENT(NORMALIZE(«$1»), « *»)»)dnl
define(«INDENT_MEMBER», «patsubst(NORMALIZE(««$1»»), «^[ ]*», « »)»)dnl
define(«DECL_ARG_TEXT», «ifelse(«$#», «1», «», «
INDENT_PARAM(«$1»):
INDENT_PARAM_DOC(«$2»)«»dnl
DECL_ARG_TEXT(shift(shift($@)))»)»)dnl
define(«PRINT_ARGS», «ifelse(«$2», «», «», «dnl
*
* Parameter(s):DECL_ARG_TEXT($@)»
)»)dnl
define(«DECLARE_FUNCTION», «dnl
/*
* «$1»(): «$2»
IFNBLANK(«$3», «dnl
*
INDENT(«$3»)
»)dnl
PRINT_ARGS($4)dnl
IFNBLANK(«$5», «dnl
*
INDENT(«$5»)
»)dnl
IFNBLANK(«$7», «dnl
*
* Return («$6»):
INDENT_RETVAL_DOC(«$7»)
»)dnl
IFNBLANK(«$8», «dnl
*
INDENT(«$8»)
»)dnl
*/
«$6» «$1»(DECL_ARGLIST($4));dnl
»)dnl
define(«STATEMENT», «dnl
/*
INDENT(«$2»)
IFNBLANK(«$3», «dnl
*
INDENT(«$3»)
»)dnl
*/
«$1»;»)dnl
define(«COMPOUND_MEMBERS», «ifelse(«$#», «1», «»,
« /*
INDENT_MEMBER_DOC(«$2»)
*/
INDENT_MEMBER(«$1»);
COMPOUND_MEMBERS(shift(shift($@)))»)»)dnl
define(«DECLARE_COMPOUND», «dnl
/*
* «$2»
IFNBLANK(«$3», «dnl
*
INDENT(«$3»)
»)dnl
*/
«$1» {
COMPOUND_MEMBERS($4)dnl
};dnl
»)dnl
define(«ENUM_MEMBERS», «ifelse(«$#», «1», «»,
« /*
INDENT_MEMBER_DOC(«$2»)
*/
INDENT_MEMBER(«$1»),
ENUM_MEMBERS(shift(shift($@)))»)»)dnl
define(«DECLARE_ENUM», «/* «$2» */
IFNBLANK(«$3», «dnl
*
patsubst(«$3», «^\s*», « * »)
»)dnl
enum «$1» {
ENUM_MEMBERS($4)dnl
};dnl
»)dnl
define(«VERBATIM_C», «NORMALIZE(«$1»)»)dnl
», OUTPUT_MODE, «HTML», «dnl --------- HTML output
define(«LINK_COUNT», 0)dnl
define(«FIXUP_LT», «patsubst(«$1», «<», «<»)»)
define(«FIXUP_GT», «patsubst(«$1», «>», «>»)»)
define(«FIXUP_AMPERSAND», «patsubst(«$1», «&», «&»)»)
define(«HANDLE_EMPTY_LINES», «patsubst(«$1», «^\s*$», «»)»)
define(«FIXUP_HTML», «FIXUP_AMPERSAND(FIXUP_LT(FIXUP_GT(««««$1»»»»)))»)
define(«FORMAT_LIST_HTML», «ifelse(«$#», «1», «», «
IFNBLANK(«$2», «
«$1»: HANDLE_EMPTY_LINES(FIXUP_HTML(««$2»»))
FORMAT_LIST_HTML(shift(shift($@)))»)»
)»)
define(«ANCHOR», «
id="link_«»LINK_COUNT"
»)
define(«HREF», «
define(«LINK_COUNT», incr(LINK_COUNT))
«$1»
»)
define(«DECLARE_FUNCTION», «
divert
| HREF(«$1()») | «$2» |
divert(«1»)
«$6» «$1»(DECL_ARGLIST($4))
FIXUP_HTML(«$2»)
HANDLE_EMPTY_LINES(FIXUP_HTML(««$3»»))
HANDLE_EMPTY_LINES(FIXUP_HTML(««$5»»))
IFNBLANK(«$7», «Return («$6»):
»)
HANDLE_EMPTY_LINES(FIXUP_HTML(««$8»»))
»)
define(«STATEMENT», «
divert
| HREF(«$1») | «$2» |
divert(«1»)
«$1»
FIXUP_HTML(«$2»)
HANDLE_EMPTY_LINES(FIXUP_HTML(««$3»»))
»)
define(«DECLARE_COMPOUND», «
divert
| HREF(«$1») | «$2» |
divert(«1»)
«$1»
FIXUP_HTML(«$2»)
HANDLE_EMPTY_LINES(FIXUP_HTML(««$3»»))
Members:
»)
define(«DECLARE_ENUM», «
divert
| HREF(«enum $1») | «$2» |
divert(«1»)
enum «$1»
FIXUP_HTML(«$2»)
HANDLE_EMPTY_LINES(FIXUP_HTML(««$3»»))
Enumeration Constants:
»)
define(«VERBATIM_C»)
divert(«1»)
divert
API Reference
»)dnl
ifdef(«EXAMPLES», «
dnl $1: name, $2: one-line summary, $3: prolog, $4: parameters,
dnl $5: parameter documentation, $6: return type, $7: return text,
dnl $8: epilog
DECLARE_FUNCTION(
«simple_func»,
«This is the one-line summary.»,
«This is the prolog.»,
«
«int param1»,
«documentation of first parameter»,
«char *param2»,
«documentation of second parameter»
»,
«This is the parameter documentation section.»,
«int»,
«This is the documentation of the return value»,
«This is the epilog.»
)
DECLARE_FUNCTION(
«complex_func»,
«Example of a function which uses all features of gendoc»,
«Prolog: The three free text sections (prolog, arg-doc and epilog) may
all consist of several paragraphs, and each may contain multiple lines.
Paragraphs are separated by lines containing only whitespace.
Formatting is kept intact, but lines are wrapped into C comments.»,
«
«int par1»,
«The parameter list consists of any number of parameter/comment
pairs. The parameters are plain C code like the "int par1" above.
The list must be quoted, and both the declaration and its
comment must also be quoted. Comments must not be empty.»,
«int par2»,
«For the parameter documentation the same rules as for the free text
sections apply: Multiple paragraphs are possible, and each may spawn
multiple lines.»
»,
«The par-doc section. It is printed after the parameter list but before
the return value (if any).
It is supposed to describe the function or its parameters in more
detail, possibly referring to one or more of the above parameters.
This function returns non-void, so this paragraph is followed by the
return value documentation.»,
«int»,
«Like the parameter/comment pairs, the return value consists of two parts:
the return type and the documentation.
This return documentation consists of two paragraphs.»,
«Finally, there is the (optional) epilog.
It might contain references to related documentation, for example a
"see also" section.»
)
DECLARE_FUNCTION(
«dwim»,
«Example of a function with no parameters and no return value.»,
«This is the description. It could consist of several paragraphs.»,
«
«void»,
»,
«Par-doc: For functions with no parameters, the par-doc section
is kind of pointless.»,
«void»,
«»,
«Epilog: For functions with no return value, the epilog directly
follows the par-doc section.»,
)
DECLARE_FUNCTION(
«minimal_documented_function»,
«This documentation conists of only the summary line.»,
«»,
«
«void»,
»,
«»,
«void»,
«»,
«»,
)
dnl $1: name, $2: one-line summary, $3: description, $4: members
DECLARE_COMPOUND(
«struct foo»,
«summary: Illustrate the DECLARE_COMPOUND macro»,
«description: The macro works for both structs and unions. The
structure of the documentation is simpler than for functions because
instead of three free-text sections (prolog, par-doc, epilog), it
has only one: the description. Of course the description may spawn
multiple paragraphs, each of which which may consist of multiple lines.
The member list is similar to the list of function parameters.»,
«
«float member1»,
«The description of the members may also spawn multiple paragraphs,
and each of them may spawn multiple lines.
This description has two paragraphs.»,
«float member2»,
«The documentation might be pretty short, though»
»
)
dnl $1: name, $2: one-line summary, $3: description, $4: members
DECLARE_ENUM(
«example_enum»,
«Summary: Illustrate the DECLARE_ENUM macro»,
«Enumerations are similar to compounds in that they receive a one-line
summary and an optional long description, The member list (paramter
#4) is expected to be a list of identifier/comment pairs.»,
«
«ENUM_ID1»,
«comment 1»,
«ENUM_ID2»,
«Comments can span multiple lines. Formatting is retained, but
leading and trailing newlines are stripped and leading tabs are
adjusted to make the C output look nice.»
»
)
dnl $1: name, $2: one-line summary, $3 description
STATEMENT(
«extern int bar»,
«Summary: Illustrate the STATMENT macro»,
«If the header file contains simple statements, they can be documented
with a one-line summary and an optional multi-paragraph description.
This is the second paragrapgh of the description.»
)
STATEMENT(
«struct opaque»,
«Summary: A statement without a description»,
)
»)dnl