X-Git-Url: http://git.tuebingen.mpg.de/?a=blobdiff_plain;f=gendoc.m4;fp=gendoc.m4;h=9bb5da82dfa9cd7a5109a02e16793975d1a5b1a9;hb=7a5132c93cde8ce79bbea3dc4568ffa5f42ec5cf;hp=0000000000000000000000000000000000000000;hpb=975357d614c27b81fbd65162a72d66d3b1a16a57;p=osl.git
diff --git a/gendoc.m4 b/gendoc.m4
new file mode 100644
index 0000000..9bb5da8
--- /dev/null
+++ b/gendoc.m4
@@ -0,0 +1,317 @@
+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