Add SCTP warning, more references

3 files changed, 64 insertions, 35 deletions

diff --git a/lib/diameter/doc/src/diameter_sctp.xml b/lib/diameter/doc/src/diameter_sctp.xml
index 03e2f1f6be..7e02a07bb4 100644
--- a/lib/diameter/doc/src/diameter_sctp.xml
+++ b/lib/diameter/doc/src/diameter_sctp.xml
@@ -60,9 +60,9 @@ and implements the behaviour documented in
 <v>Type = connect | accept</v>
 <v>Ref = <seealso marker="diameter#transport_ref">diameter:transport_ref()</seealso></v>
 <v>Svc = #diameter_service{}</v>
-<v>Opt = {raddr, inet:ip_address()} | {rport, integer()} | term()</v>
+<v>Opt = {raddr, <seealso marker="kernel:inet">inet:ip_address()</seealso>} | {rport, integer()} | term()</v>
 <v>Pid = pid()</v>
-<v>LAddr = inet:ip_address()</v>
+<v>LAddr = <seealso marker="kernel:inet">inet:ip_address()</seealso></v>
 <v>Reason = term()</v>
 </type>
 <desc>
@@ -75,12 +75,13 @@ marker="diameter_transport#start">diameter_transport(3)</seealso>.</p>
 The only diameter_sctp-specific argument is the options list.
 Options <c>raddr</c> and <c>rport</c> specify the remote address
 and port for a connecting transport and not valid for a listening
-transport.
-The former is required while latter defaults to 3868 if unspecified.
+transport: the former is required while latter defaults to 3868 if
+unspecified.
 More than one <c>raddr</c> option can be specified, in which case the
 connecting transport in question attempts each in sequence until
 an association is established.
-Remaining options are any accepted by gen_sctp:open/1, with the exception
+Remaining options are any accepted by <seealso
+marker="kernel:gen_sctp">gen_sctp:open/1</seealso>, with the exception
 of options <c>mode</c>, <c>binary</c>, <c>list</c>, <c>active</c>
 and <c>sctp_events</c>.
 Note that options <c>ip</c> and <c>port</c> specify the local address
@@ -88,30 +89,45 @@ and port respectively.</p>
 
 <p>
 Multiple <c>ip</c> options can be specified for a multihomed peer.
-If none are specified then the values of Host-IP-Address
-on the service are used. (In particular, one of these must be specified.)
+If none are specified then the values of <c>Host-IP-Address</c>
+in the <c>#diameter_service{}</c> record are used.
+(In particular, one of these must be specified.)
 Option <c>port</c> defaults to 3868 for a listening transport and 0 for a
 connecting transport.</p>
 
+<warning>
+<p>
+An insufficiently large receive buffer may result in a peer having to
+resend incoming messages: set the <seealso
+marker="kernel:inet">inet</seealso> option <c>recbuf</c> to increase
+the buffer size.</p>
+
+<p>
+An insufficiently large send buffer may result in outgoing messages
+being discarded: set the <seealso
+marker="kernel:inet">inet</seealso> option <c>sndbuf</c> to increase
+the buffer size.</p>
+</warning>
+
 <p>
 diameter_sctp uses the <c>transport_data</c> field of
-the <c>diameter_packet</c> record to communicate the stream on which an
+the <c>#diameter_packet{}</c> record to communicate the stream on which an
 inbound message has been received, or on which an outbound message
 should be sent: the value will be of the form <c>{stream, Id}</c>
 on an inbound message passed to a <seealso
 marker="diameter_app#handle_request">handle_request</seealso> or <seealso
 marker="diameter_app#handle_answer">handle_answer</seealso> callback.
-For an outbound message, either <c>undefined</c> (explicitly of
-by specifying the outbound message as a <c>binary()</c>) or a tuple
+For an outbound message, either <c>undefined</c> (explicitly or
+by receiving the outbound message as a <c>binary()</c>) or a tuple
 should be set in the return value of <seealso
 marker="diameter_app#handle_request">handle_request</seealso>
 (typically by retaining the value passed into this function)
 or <seealso
 marker="diameter_app#prepare_request">prepare_request</seealso>.
-The value <c>undefined</c> uses a "next outbound stream" id and then
-increments this modulo the total number outbound streams. That
-is, successive values of <c>undefined</c> cycle through all outbound
-streams.</p>
+The value <c>undefined</c> uses a "next outbound stream" id and
+increments this modulo the total number outbound streams.
+That is, successive values of <c>undefined</c> cycle through all
+outbound streams.</p>
 
 <!-- TODO: Some way of getting at the number of available outbound -->
 <!--       streams.                                                -->
@@ -128,7 +144,9 @@ streams.</p>
 <title>SEE ALSO</title>
 
 <p>
-<seealso marker="diameter_transport">diameter_transport(3)</seealso></p>
+<seealso marker="diameter_transport">diameter_transport(3)</seealso>,
+<seealso marker="kernel:gen_sctp">gen_sctp(3)</seealso>,
+<seealso marker="kernel:inet">inet(3)</seealso></p>
 
 </section>
 
diff --git a/lib/diameter/doc/src/diameter_tcp.xml b/lib/diameter/doc/src/diameter_tcp.xml
index 6ad98c8640..b42d65701e 100644
--- a/lib/diameter/doc/src/diameter_tcp.xml
+++ b/lib/diameter/doc/src/diameter_tcp.xml
@@ -38,8 +38,9 @@ under the License.
 <description>
 
 <p>
-This module implements diameter transport over TCP using gen_tcp.
-It can be specified as the value of a transport_module option to
+This module implements diameter transport over TCP using <seealso
+marker="kernel:gen_sctp">gen_tcp</seealso>.
+It can be specified as the value of a <c>transport_module</c> option to
 <seealso
 marker="diameter#add_transport">diameter:add_transport/2</seealso>
 and implements the behaviour documented in
@@ -67,15 +68,15 @@ before configuring TLS capability on diameter transports.</p>
 <v>Type = connect | accept</v>
 <v>Ref = <seealso marker="diameter#transport_ref">diameter:transport_ref()</seealso></v>
 <v>Svc = #diameter_service{}</v>
-<v>Opt = OwnOpt | SslOpt | OtherOpt</v>
+<v>Opt = OwnOpt | SslOpt | TcpOpt</v>
 <v>Pid = pid()</v>
-<v>LAddr = inet:ip_address()</v>
+<v>LAddr = <seealso marker="kernel:inet">inet:ip_address()</seealso></v>
 <v>Reason = term()</v>
-<v>OwnOpt = {raddr, inet:ip_address()}
+<v>OwnOpt = {raddr, <seealso marker="kernel:inet">inet:ip_address()</seealso>}
           | {rport, integer()}
           | {port, integer()}</v>
 <v>SslOpt = {ssl_options, true | list()}</v>
-<v>OtherOpt = term()</v>
+<v>TcpOpt = term()</v>
 </type>
 <desc>
 
@@ -89,25 +90,32 @@ Options <c>raddr</c> and <c>rport</c> specify the remote address
 and port for a connecting transport and are not valid for a listening
 transport.
 Option <c>ssl_options</c> must be specified for a transport
-that must be able to support TLS: a value of <c>true</c> results in a
+that should support TLS: a value of <c>true</c> results in a
 TLS handshake immediately upon connection establishment while
-list() specifies options to be passed to ssl:connect/2 of ssl:ssl_accept/2
+<c>list()</c> specifies options to be passed to <seealso
+marker="ssl:ssl">ssl:connect/2</seealso> or
+<seealso marker="ssl:ssl">ssl:ssl_accept/2</seealso>
 after capabilities exchange if TLS is negotiated.
-Remaining options are any accepted by ssl:connect/3 or gen_tcp:connect/3 for
-a connecting transport, or ssl:listen/3 or gen_tcp:listen/2 for
+Remaining options are any accepted by <seealso
+marker="ssl:ssl">ssl:connect/3</seealso> or <seealso
+marker="kernel:gen_tcp">gen_tcp:connect/3</seealso> for
+a connecting transport, or <seealso
+marker="ssl:ssl">ssl:listen/3</seealso> or <seealso
+marker="kernel:gen_tcp">gen_tcp:listen/2</seealso> for
 a listening transport, depending on whether or not <c>{ssl_options, true}</c>
 has been specified.
-Options <c>binary</c>, <c>packet</c> and <c>active</c> cannot be specified.
+Options <c>binary</c>,
+<c>packet</c> and <c>active</c> cannot be specified.
 Also, option <c>port</c> can be specified for a listening transport
 to specify the local listening port, the default being the standardized
 3868 if unspecified.
-Note that option <c>ip</c> specifies the local address.</p>
+Note that the option <c>ip</c> specifies the local address.</p>
 
 <p>
 An <c>ssl_options</c> list must be specified if and only if
-the transport in question has specified an Inband-Security-Id
-AVP with value TLS on the relevant call to
-<seealso
+the transport in question has set <c>Inband-Security-Id</c> to
+1 (<c>TLS</c>), as
+specified to either <seealso
 marker="diameter#start_service">start_service/2</seealso> or
 <seealso
 marker="diameter#add_transport">add_transport/2</seealso>,
@@ -122,9 +130,9 @@ that will not be forthcoming, which will eventually cause the RFC 3539
 watchdog to take down the connection.</p>
 
 <p>
-If the service specifies more than one Host-IP-Address and
-option <c>ip</c> is unspecified then the
-first of the service's addresses is used as the local address.</p>
+If the <c>#diameter_service{}</c> record has more than one
+<c>Host-IP-Address</c> and option <c>ip</c> is unspecified then the
+first of the these addresses is used as the local address.</p>
 
 <p>
 The returned local address list has length one.</p>
@@ -142,7 +150,10 @@ The returned local address list has length one.</p>
 
 <p>
 <seealso marker="diameter">diameter(3)</seealso>,
-<seealso marker="diameter_transport">diameter_transport(3)</seealso></p>
+<seealso marker="diameter_transport">diameter_transport(3)</seealso>,
+<seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso>,
+<seealso marker="kernel:inet">inet(3)</seealso>,
+<seealso marker="ssl:ssl">ssl(3)</seealso></p>
 
 </section>
 
diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml
index 4890333669..e852041278 100644
--- a/lib/diameter/doc/src/diameter_transport.xml
+++ b/lib/diameter/doc/src/diameter_transport.xml
@@ -63,7 +63,7 @@ parent).</p>
 <v>Svc = #diameter_service{}</v>
 <v>Opts = term()</v>
 <v>Pid = pid()</v>
-<v>LAddrs = [inet:ip_address()]</v>
+<v>LAddrs = [<seealso marker="kernel:inet">inet:ip_address()</seealso>]</v>
 <v>Reason = term()</v>
 </type>
 <desc>