aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/erl_pp.xml
diff options
context:
space:
mode:
authorHans Bolinder <hasse@erlang.org>2011-05-06 15:58:09 +0200
committerHans Bolinder <hasse@erlang.org>2011-05-12 08:03:42 +0200
commit229d0d8ca88bc344bed89e46541b325c1d267996 (patch)
tree74fec344df8596c868c36cec5ac08102008cacf3 /lib/stdlib/doc/src/erl_pp.xml
parent68fe6a14539b82250373ef114d6576e74e1b8f2e (diff)
downloadotp-229d0d8ca88bc344bed89e46541b325c1d267996.tar.gz
otp-229d0d8ca88bc344bed89e46541b325c1d267996.tar.bz2
otp-229d0d8ca88bc344bed89e46541b325c1d267996.zip
r
Use Erlang specs and types for documentation
Diffstat (limited to 'lib/stdlib/doc/src/erl_pp.xml')
-rw-r--r--lib/stdlib/doc/src/erl_pp.xml123
1 files changed, 43 insertions, 80 deletions
diff --git a/lib/stdlib/doc/src/erl_pp.xml b/lib/stdlib/doc/src/erl_pp.xml
index 1fdda48893..57b5828bcd 100644
--- a/lib/stdlib/doc/src/erl_pp.xml
+++ b/lib/stdlib/doc/src/erl_pp.xml
@@ -43,93 +43,82 @@
<p>All functions can have an optional argument which specifies a hook
that is called if an attempt is made to print an unknown form.</p>
</description>
+ <datatypes>
+ <datatype>
+ <name name="hook_function"/>
+ <desc>
+ <p>The optional argument <marker id="hook_function">
+ <c>HookFunction</c></marker>, shown in the functions described below,
+ defines a function which is called when an unknown form occurs where there
+ should be a valid expression.</p>
+
+ <p>If <c>HookFunction</c> is equal to <c>none</c> there is no hook
+ function.</p>
+
+ <p>The called hook function should return a (possibly deep) list
+ of characters. <seealso marker="#expr/4"><c>expr/4</c></seealso>
+ is useful in a hook.
+ </p>
+ <p>If <c><anno>CurrentIndentation</anno></c> is negative, there will be no line
+ breaks and only a space is used as a separator.</p>
+ </desc>
+ </datatype>
+ </datatypes>
<funcs>
<func>
- <name>form(Form) -> DeepCharList</name>
- <name>form(Form, HookFunction) -> DeepCharList</name>
+ <name name="form" arity="1"/>
+ <name name="form" arity="2"/>
<fsummary>Pretty print a form</fsummary>
- <type>
- <v>Form = term()</v>
- <v>HookFunction = see separate description below.</v>
- <v>DeepCharList = [char()|DeepCharList]</v>
- </type>
<desc>
<p>Pretty prints a
- <c>Form</c> which is an abstract form of a type which is
- returned by <c>erl_parse:parse_form</c>.</p>
+ <c><anno>Form</anno></c> which is an abstract form of a type which is
+ returned by <seealso marker="erl_parse#parse_form/1">
+ <c>erl_parse:parse_form/1</c></seealso>.</p>
</desc>
</func>
<func>
- <name>attribute(Attribute) -> DeepCharList</name>
- <name>attribute(Attribute, HookFunction) -> DeepCharList</name>
+ <name name="attribute" arity="1"/>
+ <name name="attribute" arity="2"/>
<fsummary>Pretty print an attribute</fsummary>
- <type>
- <v>Attribute = term()</v>
- <v>HookFunction = see separate description below.</v>
- <v>DeepCharList = [char()|DeepCharList]</v>
- </type>
<desc>
<p>The same as <c>form</c>, but only for the attribute
- <c>Attribute</c>.</p>
+ <c><anno>Attribute</anno></c>.</p>
</desc>
</func>
<func>
- <name>function(Function) -> DeepCharList</name>
- <name>function(Function, HookFunction) -> DeepCharList</name>
+ <name name="function" arity="1"/>
+ <name name="function" arity="2"/>
<fsummary>Pretty print a function</fsummary>
- <type>
- <v>Function = term()</v>
- <v>HookFunction = see separate description below.</v>
- <v>DeepCharList = [char()|DeepCharList]</v>
- </type>
<desc>
<p>The same as <c>form</c>, but only for the function
- <c>Function</c>.</p>
+ <c><anno>Function</anno></c>.</p>
</desc>
</func>
<func>
- <name>guard(Guard) -> DeepCharList</name>
- <name>guard(Guard, HookFunction) -> DeepCharList</name>
+ <name name="guard" arity="1"/>
+ <name name="guard" arity="2"/>
<fsummary>Pretty print a guard</fsummary>
- <type>
- <v>Form = term()</v>
- <v>HookFunction = see separate description below.</v>
- <v>DeepCharList = [char()|DeepCharList]</v>
- </type>
<desc>
<p>The same as <c>form</c>, but only for the guard test
- <c>Guard</c>.</p>
+ <c><anno>Guard</anno></c>.</p>
</desc>
</func>
<func>
- <name>exprs(Expressions) -> DeepCharList</name>
- <name>exprs(Expressions, HookFunction) -> DeepCharList</name>
- <name>exprs(Expressions, Indent, HookFunction) -> DeepCharList</name>
+ <name name="exprs" arity="1"/>
+ <name name="exprs" arity="2"/>
+ <name name="exprs" arity="3"/>
<fsummary>Pretty print <c>Expressions</c></fsummary>
- <type>
- <v>Expressions = term()</v>
- <v>HookFunction = see separate description below.</v>
- <v>Indent = integer()</v>
- <v>DeepCharList = [char()|DeepCharList]</v>
- </type>
<desc>
<p>The same as <c>form</c>, but only for the sequence of
- expressions in <c>Expressions</c>.</p>
+ expressions in <c><anno>Expressions</anno></c>.</p>
</desc>
</func>
<func>
- <name>expr(Expression) -> DeepCharList</name>
- <name>expr(Expression, HookFunction) -> DeepCharList</name>
- <name>expr(Expression, Indent, HookFunction) -> DeepCharList</name>
- <name>expr(Expression, Indent, Precedence, HookFunction) ->-> DeepCharList</name>
+ <name name="expr" arity="1"/>
+ <name name="expr" arity="2"/>
+ <name name="expr" arity="3"/>
+ <name name="expr" arity="4"/>
<fsummary>Pretty print one <c>Expression</c></fsummary>
- <type>
- <v>Expression = term()</v>
- <v>HookFunction = see separate description below.</v>
- <v>Indent = integer()</v>
- <v>Precedence = </v>
- <v>DeepCharList = [char()|DeepCharList]</v>
- </type>
<desc>
<p>This function prints one expression. It is useful for implementing hooks (see below).</p>
</desc>
@@ -137,32 +126,6 @@
</funcs>
<section>
- <title>Unknown Expression Hooks</title>
- <p>The optional argument <c>HookFunction</c>, shown in the functions described above, defines a function which is called when an unknown form occurs where there
- should be a valid expression. It can have the following formats:</p>
- <taglist>
- <tag><c>Function</c></tag>
- <item>
- <p>The hook function is called by:</p>
- <code type="none">
-Function(Expr,
- CurrentIndentation,
- CurrentPrecedence,
- HookFunction) </code>
- </item>
- <tag><c>none</c></tag>
- <item>
- <p>There is no hook function</p>
- </item>
- </taglist>
- <p>The called hook function should return a (possibly deep) list
- of characters. <c>expr/4</c> is useful in a hook.
- </p>
- <p>If <c>CurrentIndentation</c> is negative, there will be no line
- breaks and only a space is used as a separator.</p>
- </section>
-
- <section>
<title>Bugs</title>
<p>It should be possible to have hook functions for unknown forms
at places other than expressions.</p>