1 files changed, 84 insertions, 56 deletions
diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml
index 9ab750e560..55b531155f 100644
--- a/lib/diameter/doc/src/diameter_transport.xml
+++ b/lib/diameter/doc/src/diameter_transport.xml
@@ -1,5 +1,13 @@
 <?xml version="1.0" encoding="latin1" ?>
-<!DOCTYPE erlref SYSTEM "erlref.dtd">
+<!DOCTYPE erlref SYSTEM "erlref.dtd" [
+  <!ENTITY message '<seealso marker="#message">message()</seealso>'>
+  <!ENTITY ip_address
+  '<seealso marker="kernel:inet#type-ip_address">inet:ip_address()</seealso>'>
+  <!ENTITY % also SYSTEM "seealso.ent" >
+  <!ENTITY % here SYSTEM "seehere.ent" >
+  %also;
+  %here;
+]>
 
 <erlref>
 <header>
@@ -38,82 +46,116 @@ under the License.
 <description>
 
 <p>
-A module specified as a <c>transport_module</c> to <seealso
-marker="diameter#add_transport">diameter:add_transport/2</seealso>
+A module specified as a <c>transport_module</c> to &mod_add_transport;
 must implement the interface documented here.
 The interface consists of a function with which
 diameter starts a transport process and a message interface with which
 the transport process communicates with the process that starts it (aka its
 parent).</p>
 
-<marker id="start"/>
 </description>
 
 <!-- ===================================================================== -->
 
+<section>
+<title>DATA TYPES</title>
+
+<taglist>
+
+<marker id="message"/>
+
+<tag><c>message() = binary() | &codec_packet;</c></tag>
+<item>
+<p>
+A Diameter message as passed over the transport interface.</p>
+
+<p>
+For an inbound message from a transport process, a &codec_packet; must
+contain the received message in its <c>bin</c> field.
+In the case of an inbound request, any value set in the
+<c>transport_data</c> field will passed back to the transport module
+in the corresponding answer message, unless the sender supplies
+another value.</p>
+
+<p>
+For an outbound message to a transport process, a &codec_packet; has a
+value other than <c>undefined</c> in its <c>transport_data</c> field
+and has the binary() to send in its <c>bin</c> field.</p>
+</item>
+
+</taglist>
+
+</section>
+
+<!-- ===================================================================== -->
+
 <funcs>
 
 <func>
-<name>Mod:start({Type, Ref}, Svc, Opts)
-         -> {ok, Pid} | {ok, Pid, LAddrs} | {error, Reason}</name>
+<name>Mod:start({Type, Ref}, Svc, Config)
+         -> {ok, Pid}
+          | {ok, Pid, LAddrs}
+          | {error, Reason}</name>
 <fsummary>Start a transport process.</fsummary>
 <type>
 <v>Type = connect | accept</v>
-<v>Ref = <seealso marker="diameter#transport_ref">diameter:transport_ref()</seealso></v>
+<v>Ref = &mod_transport_ref;</v>
 <v>Svc = #diameter_service{}</v>
-<v>Opts = term()</v>
+<v>Config = term()</v>
 <v>Pid = pid()</v>
-<v>LAddrs = [<seealso marker="kernel:inet#type-ip_address">inet:ip_address()</seealso>]</v>
+<v>LAddrs = [&ip_address;]</v>
 <v>Reason = term()</v>
 </type>
 <desc>
 <p>
 Start a transport process.
-Called by diameter as a consequence of a call to <seealso
-marker="diameter#add_transport">diameter:add_transport/2</seealso> in
+Called by diameter as a consequence of a call to &mod_add_transport; in
 order to establish or accept a transport connection respectively.
 A transport process maintains a connection with a single remote peer.</p>
 
 <p>
-The first argument indicates whether the transport process in question
-is being started for a connecting (<c>connect</c>) or listening
-(<c>accept</c>) transport.
+<c>Type</c> indicates whether the transport process in question
+is being started for a connecting (<c>Type=connect</c>) or listening
+(<c>Type=accept</c>) transport.
 In the latter case, transport processes are started as required to
-accept connections from multiple peers.
-Ref is in each case the same value that was returned from the
-call to <seealso
-marker="diameter#add_transport">diameter:add_transport/2</seealso>
+accept connections from multiple peers.</p>
+
+<p>
+Ref is the value that was returned from the call to &mod_add_transport;
 that has lead to starting of a transport process.</p>
 
 <p>
-A transport process must implement the message interface documented below.
-It should retain the pid of its parent, monitor the parent and terminate if
-it dies.
-It should not link to the parent.
-It should exit if its transport connection with its peer is lost.</p>
+<c>Svc</c> contains the capabilities passed to &mod_start_service; and
+&mod_add_transport;, values passed to the latter overriding those
+passed to the former.</p>
+
+<p>
+<c>Config</c> is as passed in <c>transport_config</c> tuple in the
+&mod_transport_opt; list passed to &mod_add_transport;.</p>
 
 <p>
-The capabilities in the <c>#diameter_service{}</c> record are as
-passed to <seealso
-marker="diameter#start_service">diameter:start_service/2</seealso> and 
-<seealso
-marker="diameter#add_transport">diameter:add_transport/2</seealso>,
-values passed to the latter overriding those passed to the former.
 The start function should use the <c>Host-IP-Address</c> list and/or
-<c>Opts</c> to select an appropriate list of local IP addresses,
+<c>Config</c> to select an appropriate list of local IP addresses,
 and should return this list if different from the
 <c>#diameter_service{}</c> addresses.
 The returned list is used to populate <c>Host-IP-Address</c> AVPs in
 outgoing capabilities exchange messages, the
 <c>#diameter_service{}</c> addresses being used otherwise.</p>
 
-<marker id="MESSAGES"/>
+<p>
+A transport process must implement the message interface documented below.
+It should retain the pid of its parent, monitor the parent and terminate if
+it dies.
+It should not link to the parent.
+It should exit if its transport connection with its peer is lost.</p>
+
 </desc>
 </func>
 
 </funcs>
 
 <!-- ===================================================================== -->
+<marker id="MESSAGES"/>
 
 <section>
 <title>MESSAGES</title>
@@ -123,27 +165,23 @@ All messages sent over the transport interface are of the
 form <c>{diameter, term()}</c>.</p>
 
 <p>
-A transport process can expect the following messages from
-diameter.</p>
+A transport process can expect messages of the following types from
+its parent.</p>
 
 <taglist>
 
-<tag><c>{diameter, {send, Packet}}</c></tag>
+<tag><c>{diameter, {send, &message;}}</c></tag>
 <item>
 <p>
-An outbound Diameter message.
-<c>Packet</c> can be either binary() (the message to be sent)
-or a <c>#diameter_packet{}</c> record whose <c>transport_data</c>
-field contains a value other than undefined and whose <c>bin</c> field
-contains the binary to send.</p>
+An outbound Diameter message.</p>
 </item>
 
 <tag><c>{diameter, {close, Pid}}</c></tag>
 <item>
 <p>
-A request to close the transport connection.
-The transport process should terminate after closing the
-connection.
+A request to terminate the transport process after having received DPA
+in response to DPR.
+The transport process should exit.
 <c>Pid</c> is the pid() of the parent process.</p>
 </item>
 
@@ -178,7 +216,7 @@ TLS.</p>
 </taglist>
 
 <p>
-A transport process should send the following messages
+A transport process should send messages of the following types
 to its parent.</p>
 
 <taglist>
@@ -201,19 +239,10 @@ Not sent if the transport process has <c>Type=accept</c>.
 endpoint to which the transport has connected.</p>
 </item>
 
-<tag><c>{diameter, {recv, Packet}}</c></tag>
+<tag><c>{diameter, {recv, &message;}}</c></tag>
 <item>
 <p>
-An inbound Diameter message.
-<c>Packet</c> can be either binary() (the received message)
-or a <c>#diameter_packet{}</c> record
-whose <c>bin</c> field contains the received binary().
-Any value (other than <c>undefined</c>) set in
-the <c>transport_data</c> field will be passed back with a
-corresponding answer message in the case that the inbound message is a
-request unless the sender sets another value.
-How <c>transport_data</c> is used/interpreted is up to the
-transport module.</p>
+An inbound Diameter message.</p>
 </item>
 
 <tag><c>{diameter, {tls, Ref}}</c></tag>
@@ -237,8 +266,7 @@ A transport must exit if a handshake is not successful.</p>
 <title>SEE ALSO</title>
 
 <p>
-<seealso marker="diameter_tcp">diameter_tcp(3)</seealso>,
-<seealso marker="diameter_sctp">diameter_sctp(3)</seealso></p>
+&man_tcp;, &man_sctp;</p>
 
 </section>