Merge branch 'hb/kernel/doc_specs/OTP-9272' into dev

* hb/kernel/doc_specs/OTP-9272:
  Use Erlang specs and types for documentation

1 files changed, 46 insertions, 83 deletions

diff --git a/lib/kernel/doc/src/erl_ddll.xml b/lib/kernel/doc/src/erl_ddll.xml
index 9a62b45d63..f9514dda2f 100644
--- a/lib/kernel/doc/src/erl_ddll.xml
+++ b/lib/kernel/doc/src/erl_ddll.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1997</year><year>2010</year>
+      <year>1997</year><year>2011</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -172,6 +172,14 @@
       </item>
     </taglist>
   </description>
+  <datatypes>
+    <datatype>
+      <name name="driver"/>
+    </datatype>
+    <datatype>
+      <name name="path"/>
+    </datatype>
+  </datatypes>
   <funcs>
     <func>
       <name>demonitor(MonitorRef) -> ok</name>
@@ -189,37 +197,21 @@
       </desc>
     </func>
     <func>
-      <name>info() -> AllInfoList</name>
+      <name name="info" arity="0"/>
       <fsummary>Retrieve information about all drivers</fsummary>
-      <type>
-        <v>AllInfoList = [ DriverInfo ]</v>
-        <v>DriverInfo = {DriverName, InfoList}</v>
-        <v>DriverName = string()</v>
-        <v>InfoList = [ InfoItem ]</v>
-        <v>InfoItem = {Tag, Value}</v>
-        <v>Tag = atom()</v>
-        <v>Value = term()</v>
-      </type>
       <desc>
-        <p>Returns a list of tuples <c>{DriverName, InfoList}</c>, where
-          <c>InfoList</c> is the result of calling <seealso marker="#info/1">info/1</seealso> for that
-          <c>DriverName</c>. Only dynamically linked in drivers are
+        <p>Returns a list of tuples <c>{<anno>DriverName</anno>, <anno>InfoList</anno>}</c>, where
+          <c><anno>InfoList</anno></c> is the result of calling <seealso marker="#info/1">info/1</seealso> for that
+          <c><anno>DriverName</anno></c>. Only dynamically linked in drivers are
           included in the list.</p>
       </desc>
     </func>
     <func>
-      <name>info(Name) -> InfoList</name>
+      <name name="info" arity="1"/>
       <fsummary>Retrieve information about one driver</fsummary>
-      <type>
-        <v>Name = string() | atom()</v>
-        <v>InfoList = [ InfoItem ]</v>
-        <v>InfoItem = {Tag, Value}</v>
-        <v>Tag = atom()</v>
-        <v>Value = term()</v>
-      </type>
       <desc>
-        <p>Returns a list of tuples <c>{Tag, Value}</c>, where
-          <c>Tag</c> is the information item and <c>Value</c> is the result
+        <p>Returns a list of tuples <c>{<anno>Tag</anno>, <anno>Value</anno>}</c>, where
+          <c><anno>Tag</anno></c> is the information item and <c><anno>Value</anno></c> is the result
           of calling <seealso marker="#info/2">info/2</seealso> with this driver name and
           this tag. The result being a tuple list containing all
           information available about a driver. </p>
@@ -305,22 +297,18 @@
       </desc>
     </func>
     <func>
-      <name>load(Path, Name) -> ok | {error, ErrorDesc}</name>
+      <name name="load" arity="2"/>
       <fsummary>Load a driver</fsummary>
-      <type>
-        <v>Path = Name = string() | atom()</v>
-        <v>ErrorDesc = term()</v>
-      </type>
       <desc>
-        <p>Loads and links the dynamic driver <c>Name</c>. <c>Path</c>
+        <p>Loads and links the dynamic driver <c><anno>Name</anno></c>. <c><anno>Path</anno></c>
           is a file path to the directory containing the driver.
-          <c>Name</c> must be a sharable object/dynamic library. Two
-          drivers with different <c>Path</c> parameters cannot be
-          loaded under the same name. The <c>Name</c> is a string or
+          <c><anno>Name</anno></c> must be a sharable object/dynamic library. Two
+          drivers with different <c><anno>Path</anno></c> parameters cannot be
+          loaded under the same name. The <c><anno>Name</anno></c> is a string or
           atom containing at least one character.</p>
-        <p>The <c>Name</c> given should correspond to the filename
+        <p>The <c><anno>Name</anno></c> given should correspond to the filename
           of the actual dynamically loadable object file residing in
-          the directory given as <c>Path</c>, but <em>without</em> the
+          the directory given as <c><anno>Path</anno></c>, but <em>without</em> the
           extension (i.e. <c>.so</c>). The driver name provided in
           the driver initialization routine must correspond with the
           filename, in much the same way as erlang module names
@@ -328,14 +316,14 @@
         <p>If the driver has been previously unloaded, but is still
           present due to open ports against it, a call to
           <c>load/2</c> will stop the unloading and keep the driver
-          (as long as the <c>Path</c> is the same) and <c>ok</c> is
+          (as long as the <c><anno>Path</anno></c> is the same) and <c>ok</c> is
           returned. If one actually wants the object code to be
           reloaded, one uses <seealso marker="#reload/2">reload/2</seealso> or the low-level
           interface <seealso marker="#try_load/3">try_load/3</seealso>
           instead. Please refer to the description of <seealso marker="#scenarios">different scenarios</seealso> for
           loading/unloading in the introduction.</p>
         <p>If more than one process tries to load an already loaded
-          driver withe the same <c>Path</c>, or if the same process
+          driver withe the same <c><anno>Path</anno></c>, or if the same process
           tries to load it several times, the function will return
           <c>ok</c>.  The emulator will keep track of the
           <c>load/2</c> calls, so that a corresponding number of
@@ -349,16 +337,16 @@
           several drivers with the same name but with different
           <c>Path</c> parameters.</p>
         <note>
-          <p>Note especially that the <c>Path</c> is interpreted
+          <p>Note especially that the <c><anno>Path</anno></c> is interpreted
             literally, so that all loaders of the same driver needs to
-            give the same <em>literal</em><c>Path</c> string, even
+            give the same <em>literal</em><c><anno>Path</anno></c> string, even
             though different paths might point out the same directory
             in the filesystem (due to use of relative paths and
             links).</p>
         </note>
         <p>On success, the function returns <c>ok</c>. On
-          failure, the return value is <c>{error,ErrorDesc}</c>,
-          where <c>ErrorDesc</c> is an opaque term to be
+          failure, the return value is <c>{error,<anno>ErrorDesc</anno>}</c>,
+          where <c><anno>ErrorDesc</anno></c> is an opaque term to be
           translated into human readable form by the <seealso marker="#format_error/1">format_error/1</seealso>
           function.</p>
         <p>For more control over the error handling, again use the
@@ -369,20 +357,16 @@
       </desc>
     </func>
     <func>
-      <name>load_driver(Path, Name) -> ok | {error, ErrorDesc}</name>
+      <name name="load_driver" arity="2"/>
       <fsummary>Load a driver</fsummary>
-      <type>
-        <v>Path = Name = string() | atom()</v>
-        <v>ErrorDesc = term()</v>
-      </type>
       <desc>
         <p>Works essentially as <c>load/2</c>, but will load the driver
-          with options other options.  All ports that are using the
+          with other options.  All ports that are using the
           driver will get killed with the reason
           <c>driver_unloaded</c> when the driver is to be unloaded.</p>
         <p>The number of loads and unloads by different <seealso marker="#users">users</seealso> influence the actual loading
           and unloading of a driver file. The port killing will
-          therefore only happen when the <em>last</em><seealso marker="#users">user</seealso> unloads the driver, or the
+          therefore only happen when the <em>last</em> <seealso marker="#users">user</seealso> unloads the driver, or the
           last process having loaded the driver exits.</p>
         <p>This interface (or at least the name of the functions) is
           kept for backward compatibility.  Using <seealso marker="#try_load/3">try_load/3</seealso> with
@@ -551,16 +535,11 @@
       </desc>
     </func>
     <func>
-      <name>reload(Path, Name) -> ok | {error, ErrorDesc}</name>
+      <name name="reload" arity="2"/>
       <fsummary>Replace a driver</fsummary>
-      <type>
-        <v>Path = Name = string() | atom()</v>
-        <v>ErrorDesc = pending_process | OpaqueError</v>
-        <v>OpaqueError = term()</v>
-      </type>
       <desc>
-        <p>Reloads the driver named <c>Name</c> from a possibly
-          different <c>Path</c> than was previously used. This
+        <p>Reloads the driver named <c><anno>Name</anno></c> from a possibly
+          different <c><anno>Path</anno></c> than was previously used. This
           function is used in the code change <seealso marker="#scenarios">scenario</seealso> described in the
           introduction.</p>
         <p>If there are other <seealso marker="#users">users</seealso>
@@ -574,7 +553,7 @@
         <p>If one wants to avoid hanging on open ports, one should use
           the <seealso marker="#try_load/3">try_load/3</seealso>
           function instead.</p>
-        <p>The <c>Name</c> and <c>Path</c> parameters have exactly the
+        <p>The <c><anno>Name</anno></c> and <c><anno>Path</anno></c> parameters have exactly the
           same meaning as when calling the plain <seealso marker="#load/2">load/2</seealso> function.</p>
         <note>
           <p>Avoid mixing
@@ -594,13 +573,8 @@
       </desc>
     </func>
     <func>
-      <name>reload_driver(Path, Name) -> ok | {error, ErrorDesc}</name>
+      <name name="reload_driver" arity="2"/>
       <fsummary>Replace a driver</fsummary>
-      <type>
-        <v>Path = Name = string() | atom()</v>
-        <v>ErrorDesc = pending_process | OpaqueError</v>
-        <v>OpaqueError = term()</v>
-      </type>
       <desc>
         <p>Works exactly as <seealso marker="#reload/2">reload/2</seealso>, but for drivers
           loaded with the <seealso marker="#load_driver/2">load_driver/2</seealso> interface. </p>
@@ -1066,15 +1040,11 @@
       </desc>
     </func>
     <func>
-      <name>unload(Name) -> ok | {error, ErrorDesc}</name>
+      <name name="unload" arity="1"/>
       <fsummary>Unload a driver</fsummary>
-      <type>
-        <v>Name = string() | atom()</v>
-        <v>ErrorDesc = term()</v>
-      </type>
       <desc>
         <p>Unloads, or at least dereferences the driver named
-          <c>Name</c>. If the caller is the last <seealso marker="#users">user</seealso> of the driver, and there
+          <c><anno>Name</anno></c>. If the caller is the last <seealso marker="#users">user</seealso> of the driver, and there
           are no more open ports using the driver, the driver will
           actually get unloaded. In all other cases, actual unloading
           will be delayed until all ports are closed and there are no
@@ -1084,7 +1054,7 @@
           is no longer considered a user of the driver. For usage
           scenarios, see the <seealso marker="#scenarios">description</seealso> in the beginning
           of this document. </p>
-        <p>The <c>ErrorDesc</c> returned is an opaque value to be
+        <p>The <c><anno>ErrorDesc</anno></c> returned is an opaque value to be
           passed further on to the <seealso marker="#format_error/1">format_error/1</seealso>
           function. For more control over the operation, use the
           <seealso marker="#try_unload/2">try_unload/2</seealso>
@@ -1094,15 +1064,11 @@
       </desc>
     </func>
     <func>
-      <name>unload_driver(Name) -> ok | {error, ErrorDesc}</name>
+      <name name="unload_driver" arity="1"/>
       <fsummary>Unload a driver</fsummary>
-      <type>
-        <v>Name = string() | atom()</v>
-        <v>ErrorDesc = term()</v>
-      </type>
       <desc>
         <p>Unloads, or at least dereferences the driver named
-          <c>Name</c>. If the caller is the last <seealso marker="#users">user</seealso> of the driver, all
+          <c><anno>Name</anno></c>. If the caller is the last <seealso marker="#users">user</seealso> of the driver, all
           remaining open ports using the driver will get killed with
           the reason <c>driver_unloaded</c> and the driver will
           eventually get unloaded.</p>
@@ -1112,7 +1078,7 @@
           <seealso marker="#users">user</seealso>. For
           usage scenarios, see the <seealso marker="#scenarios">description</seealso> in the beginning
           of this document.</p>
-        <p>The <c>ErrorDesc</c> returned is an opaque value to be
+        <p>The <c><anno>ErrorDesc</anno></c> returned is an opaque value to be
           passed further on to the <seealso marker="#format_error/1">format_error/1</seealso>
           function. For more control over the operation, use the
           <seealso marker="#try_unload/2">try_unload/2</seealso>
@@ -1125,7 +1091,7 @@
       <name>loaded_drivers() -> {ok, Drivers}</name>
       <fsummary>List loaded drivers</fsummary>
       <type>
-        <v>Drivers = [Driver()]</v>
+        <v>Drivers = [Driver]</v>
         <v>Driver = string()</v>
       </type>
       <desc>
@@ -1138,13 +1104,10 @@
       </desc>
     </func>
     <func>
-      <name>format_error(ErrorDesc) -> string()</name>
+      <name name="format_error" arity="1"/>
       <fsummary>Format an error descriptor</fsummary>
-      <type>
-        <v>ErrorDesc -- see below</v>
-      </type>
       <desc>
-        <p>Takes an <c>ErrorDesc</c> returned by load, unload or
+        <p>Takes an <c><anno>ErrorDesc</anno></c> returned by load, unload or
           reload functions and returns a string which
           describes the error or warning.</p>
         <note>