Merge branch 'anders/diameter/documentation/OTP-10216' into maint

* anders/diameter/documentation/OTP-10216:
  Fix broken references
  Correct doc on AVP P flag and add warning about its deprecation
  Fix/tweak references to other applications
  Minor formatting fixes
  Add warning about 'host' filter
  Update diameterc doc
  Minor updates/corrections to Users Guide
  Add SCTP warning, more references
  Assorted doc improvements
  Document service info
  Document watchdog events
  Terminology and other clarifications, more references
  Clarify documentation on application state

1 files changed, 35 insertions, 31 deletions

diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml
index 087a90b099..1bd45d9ce8 100644
--- a/lib/diameter/doc/src/diameter_transport.xml
+++ b/lib/diameter/doc/src/diameter_transport.xml
@@ -59,11 +59,11 @@ parent).</p>
 <fsummary>Start a transport process.</fsummary>
 <type>
 <v>Type = connect | accept</v>
-<v>Ref = reference()</v>
+<v>Ref = <seealso marker="diameter#transport_ref">diameter:transport_ref()</seealso></v>
 <v>Svc = #diameter_service{}</v>
 <v>Opts = term()</v>
 <v>Pid = pid()</v>
-<v>LAddrs = [ip_address()]</v>
+<v>LAddrs = [<seealso marker="kernel:inet#type-ip_address">inet:ip_address()</seealso>]</v>
 <v>Reason = term()</v>
 </type>
 <desc>
@@ -93,16 +93,19 @@ It should not link to the parent.
 It should exit if its transport connection with its peer is lost.</p>
 
 <p>
-Transport processes for a given service are started sequentially.</p>
-
-<p>
-The start function should use the 'Host-IP-Address' list on the service,
-namely <c>Svc#diameter_service.host_ip_address</c>, and/or
+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,
-and should return this list if different from the service addresses.
-The returned list is used to populate 'Host-IP-Address' AVPs in outgoing
-capabilities exchange messages, the service addresses being used
-otherwise.</p>
+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"/>
 </desc>
@@ -129,9 +132,10 @@ diameter.</p>
 <item>
 <p>
 An outbound Diameter message.
-Packet can be either <c>binary()</c> (the message to be sent)
-or a <c>#diameter_packet{}</c> whose <c>transport_data</c> field
-containes a value other than undefined.</p>
+<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>
 </item>
 
 <tag><c>{diameter, {close, Pid}}</c></tag>
@@ -140,7 +144,7 @@ containes a value other than undefined.</p>
 A request to close the transport connection.
 The transport process should terminate after closing the
 connection.
-Pid is the pid() of the parent process.</p>
+<c>Pid</c> is the pid() of the parent process.</p>
 </item>
 
 <tag><c>{diameter, {tls, Ref, Type, Bool}}</c></tag>
@@ -148,17 +152,17 @@ Pid is the pid() of the parent process.</p>
 <p>
 Indication of whether or not capabilities exchange has selected
 inband security using TLS.
-Ref is a reference() that must be included in the
+<c>Ref</c> is a reference() that must be included in the
 <c>{diameter, {tls, Ref}}</c> reply message to the transport's
 parent process (see below).
-Type is either <c>connect</c> or <c>accept</c> depending on
+<c>Type</c> is either <c>connect</c> or <c>accept</c> depending on
 whether the process has been started for a connecting or listening
 transport respectively.
-Bool is a boolean() indicating whether or not the transport connection
-should be upgraded to TLS.</p>
+<c>Bool</c> is a boolean() indicating whether or not the transport
+connection should be upgraded to TLS.</p>
 
 <p>
-If TLS is requested (Bool = true) then a connecting process should
+If TLS is requested (<c>Bool=true</c>) then a connecting process should
 initiate a TLS handshake with the peer and an accepting process should
 prepare to accept a handshake.
 A successful handshake should be followed by a <c>{diameter, {tls, Ref}}</c>
@@ -182,18 +186,18 @@ to its parent.</p>
 <tag><c>{diameter, {self(), connected}}</c></tag>
 <item>
 <p>
-Inform the parent that the transport process with Type = accept has
+Inform the parent that the transport process with <c>Type=accept</c> has
 established a connection with the peer.
-Not sent if the transport process has Type = connect.</p>
+Not sent if the transport process has <c>Type=connect</c>.</p>
 </item>
 
 <tag><c>{diameter, {self(), connected, Remote}}</c></tag>
 <item>
 <p>
-Inform the parent that the transport process with Type = connect
+Inform the parent that the transport process with <c>Type=connect</c>
 has established a connection with a peer.
-Not sent if the transport process has Type = accept.
-Remote is an arbitrary term that uniquely identifies the remote
+Not sent if the transport process has <c>Type=accept</c>.
+<c>Remote</c> is an arbitrary term that uniquely identifies the remote
 endpoint to which the transport has connected.</p>
 </item>
 
@@ -201,14 +205,14 @@ endpoint to which the transport has connected.</p>
 <item>
 <p>
 An inbound Diameter message.
-Packet can be either <c>binary()</c> (the message to be sent)
-or <c>#diameter_packet{}</c>
-whose <c>packet</c> field contains a <c>binary()</c>.
-Any value (other than undefined) set in
+<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 the <c>transport_data</c> is used/interpreted is up to the
+How <c>transport_data</c> is used/interpreted is up to the
 transport module.</p>
 </item>
 
@@ -216,7 +220,7 @@ transport module.</p>
 <item>
 <p>
 Acknowledgment of a successful TLS handshake.
-Ref is the reference() received in the
+<c>Ref</c> is the reference() received in the
 <c>{diameter, {tls, Ref, Type, Bool}}</c> message in response
 to which the reply is sent.
 A transport must exit if a handshake is not successful.</p>