Merge branch 'hb/stdlib/doc_specs/OTP-9271' into dev

* hb/stdlib/doc_specs/OTP-9271:
  Use Erlang specs and types for documentation

Conflicts:
	lib/stdlib/doc/src/timer.xml

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>