Terminology and other clarifications, more references

Diameter node/peer having been the most vicious terminology blunder.

5 files changed, 189 insertions, 146 deletions

diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml
index 10139b90c7..6abd1515c9 100644
--- a/lib/diameter/doc/src/diameter.xml
+++ b/lib/diameter/doc/src/diameter.xml
@@ -49,7 +49,7 @@ Diameter protocol as defined in RFC 3588.</p>
 
 <p>
 Basic usage consists of creating a representation of a
-locally implemented Diameter peer and its capabilities with <seealso
+locally implemented Diameter node and its capabilities with <seealso
 marker="#start_service">start_service/2</seealso>, adding transport
 capability using <seealso
 marker="#add_transport">add_transport/2</seealso> and sending Diameter
@@ -84,13 +84,14 @@ this module.</p>
 
 <tag><c>Address()</c></tag>
 <tag><c>DiameterIdentity()</c></tag>
+<tag><c>Grouped()</c></tag>
+<tag><c>OctetString()</c></tag>
 <tag><c>Time()</c></tag>
 <tag><c>Unsigned32()</c></tag>
-<tag><c>UTF8String()</c></tag>
 <item>
 <p>
 Types corresponding to RFC 3588 AVP Data Formats.
-Defined in <seealso marker="diameter_dict">diameter_dict(4)</seealso>.</p>
+Defined in <seealso marker="diameter_dict#DATA_TYPES">diameter_dict(4)</seealso>.</p>
 
 <marker id="application_alias"/>
 </item>
@@ -148,7 +149,7 @@ Options defining a Diameter application as configured in an
 
 <taglist>
 
-<tag><c>{alias, application_alias()}</c></tag>
+<tag><c>{alias, <seealso marker="#application_alias">application_alias()</seealso>}</c></tag>
 <item>
 <p>
 An unique identifier for the application in the scope of the
@@ -166,7 +167,7 @@ documented in <seealso
 marker="diameter_dict">diameter_dict(4)</seealso>.</p>
 </item>
 
-<tag><c>{module, application_module()}</c></tag>
+<tag><c>{module, <seealso marker="#application_module">application_module()</seealso>}</c></tag>
 <item>
 <p>
 A callback module with which messages of the Diameter application are
@@ -253,7 +254,7 @@ itself.
 Multiple options append to the argument list.</p>
 </item>
 
-<tag><c>{filter, peer_filter()}</c></tag>
+<tag><c>{filter, <seealso marker="#peer_filter">peer_filter()</seealso>}</c></tag>
 <item>
 <p>
 A filter to apply to the list of available peers before passing them to
@@ -264,7 +265,7 @@ corresponding list of filters.
 Defaults to <c>none</c>.</p>
 </item>
 
-<tag><c>{timeout, Unsigned32()}</c></tag>
+<tag><c>{timeout, <seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>}</c></tag>
 <item>
 <p>
 The number of milliseconds after which the request should
@@ -304,19 +305,19 @@ precedence over the former.</p>
 
 <taglist>
 
-<tag><c>{'Origin-Host', DiameterIdentity()}</c></tag>
+<tag><c>{'Origin-Host', <seealso marker="diameter_dict#DATA_TYPES">DiameterIdentity()</seealso>}</c></tag>
 <item>
 <p>
 Value of the Origin-Host AVP in outgoing messages.</p>
 </item>
 
-<tag><c>{'Origin-Realm', DiameterIdentity()}</c></tag>
+<tag><c>{'Origin-Realm', <seealso marker="diameter_dict#DATA_TYPES">DiameterIdentity()</seealso>}</c></tag>
 <item>
 <p>
 Value of the Origin-Realm AVP in outgoing messages.</p>
 </item>
 
-<tag><c>{'Host-IP-Address', [Address()]}</c></tag>
+<tag><c>{'Host-IP-Address', [<seealso marker="diameter_dict#DATA_TYPES">Address()</seealso>]}</c></tag>
 <item>
 <p>
 Values of Host-IP-Address AVPs.
@@ -325,26 +326,25 @@ Optional.</p>
 <p>
 The list of addresses is available to the start function of a
 transport module, which either uses them as is or returns a new list
-(typically as configured as <c>transport_config()</c> on the
-transport module in question) in order for the correct list of
-addresses to be sent in capabilities exchange messages.</p>
+in order for the correct list of addresses to be sent in capabilities
+exchange messages.</p>
 </item>
 
-<tag><c>{'Vendor-Id', Unsigned32()}</c></tag>
+<tag><c>{'Vendor-Id', <seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>}</c></tag>
 <item>
 <p>
 Value of the Vendor-Id AVP sent in an outgoing capabilities
 exchange message.</p>
 </item>
 
-<tag><c>{'Product-Name', UTF8String()}</c></tag>
+<tag><c>{'Product-Name', <seealso marker="#UTF8String">UTF8String()</seealso>}</c></tag>
 <item>
 <p>
 Value of the Product-Name AVP sent in an outgoing capabilities
 exchange message.</p>
 </item>
 
-<tag><c>{'Origin-State-Id', Unsigned32()}</c></tag>
+<tag><c>{'Origin-State-Id', <seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>}</c></tag>
 <item>
 <p>
 Value of Origin-State-Id to be included in outgoing messages sent by
@@ -361,7 +361,7 @@ can be used as to retrieve a value that is set when the diameter
 application is started.</p>
 </item>
 
-<tag><c>{'Supported-Vendor-Id', [Unsigned32()]}</c></tag>
+<tag><c>{'Supported-Vendor-Id', [<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>]}</c></tag>
 <item>
 <p>
 Values of Supported-Vendor-Id AVPs sent in an outgoing
@@ -369,7 +369,7 @@ capabilities exchange message.
 Optional, defaults to the empty list.</p>
 </item>
 
-<tag><c>{'Auth-Application-Id', [Unsigned32()]}</c></tag>
+<tag><c>{'Auth-Application-Id', [<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>]}</c></tag>
 <item>
 <p>
 Values of Auth-Application-Id AVPs sent in an outgoing
@@ -377,7 +377,7 @@ capabilities exchange message.
 Optional, defaults to the empty list.</p>
 </item>
 
-<tag><c>{'Inband-Security-Id', [Unsigned32()]}</c></tag>
+<tag><c>{'Inband-Security-Id', [<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>]}</c></tag>
 <item>
 <p>
 Values of Inband-Security-Id AVPs sent in an outgoing
@@ -390,7 +390,7 @@ If 1 (= TLS) is specified then TLS is selected if the CER/CEA received
 from the peer offers it.</p>
 </item>
 
-<tag><c>{'Acct-Application-Id', [Unsigned32()]}</c></tag>
+<tag><c>{'Acct-Application-Id', [<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>]}</c></tag>
 <item>
 <p>
 Values of Acct-Application-Id AVPs sent in an outgoing
@@ -398,7 +398,7 @@ capabilities exchange message.
 Optional, defaults to the empty list.</p>
 </item>
 
-<tag><c>{'Vendor-Specific-Application-Id', [Grouped()]}</c></tag>
+<tag><c>{'Vendor-Specific-Application-Id', [<seealso marker="diameter_dict#DATA_TYPES">Grouped()</seealso>]}</c></tag>
 <item>
 <p>
 Values of Vendor-Specific-Application-Id AVPs sent in
@@ -406,7 +406,7 @@ an outgoing capabilities exchange message.
 Optional, defaults to the empty list.</p>
 </item>
 
-<tag><c>{'Firmware-Revision', Unsigned32()}</c></tag>
+<tag><c>{'Firmware-Revision', <seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>}</c></tag>
 <item>
 <p>
 Value of the Firmware-Revision AVP sent in an outgoing capabilities
@@ -490,41 +490,42 @@ or any peer if the request does not contain
 a <c>Destination-Realm</c> AVP.</p>
 </item>
 
-<tag><c>{host, any|DiameterIdentity()}</c></tag>
+<tag><c>{host, any|<seealso marker="diameter_dict#DATA_TYPES">DiameterIdentity()</seealso>}</c></tag>
 <item>
 <p>
 Matches only those peers whose <c>Origin-Host</c> has the
 specified value, or all peers if the atom <c>any</c>.</p>
 </item>
 
-<tag><c>{realm, any|DiameterIdentity()</c></tag>
+<tag><c>{realm, any|<seealso marker="diameter_dict#DATA_TYPES">DiameterIdentity()</seealso></c></tag>
 <item>
 <p>
 Matches only those peers whose <c>Origin-Realm</c> has the
 value, or all peers if the atom <c>any</c>.</p>
 </item>
 
-<tag><c>{eval, evaluable()}</c></tag>
+<tag><c>{eval, <seealso marker="#evaluable">evaluable()</seealso>}</c></tag>
 <item>
 <p>
-Matches only those peers for which the specified evaluable() returns
+Matches only those peers for which the specified <seealso
+marker="evaluable">#evaluable()</seealso> returns
 <c>true</c> on the connection's <c>diameter_caps</c> record.
 Any other return value or exception is equivalent to <c>false</c>.</p>
 </item>
 
-<tag><c>{neg, peer_filter()}</c></tag>
+<tag><c>{neg, <seealso marker="#peer_filter">peer_filter()</seealso>}</c></tag>
 <item>
 <p>
 Matches only those peers not matched by the specified filter.</p>
 </item>
 
-<tag><c>{all, [peer_filter()]}</c></tag>
+<tag><c>{all, [<seealso marker="#peer_filter">peer_filter()</seealso>]}</c></tag>
 <item>
 <p>
 Matches only those peers matched by each filter of the specified list.</p>
 </item>
 
-<tag><c>{any, [peer_filter()]}</c></tag>
+<tag><c>{any, [<seealso marker="#peer_filter">peer_filter()</seealso>]}</c></tag>
 <item>
 <p>
 Matches only those peers matched by at least one filter of the
@@ -536,10 +537,11 @@ specified list.</p>
 <p>
 Note that the <c>host</c> and <c>realm</c> filters examine the
 outgoing request as passed to <seealso marker="#call">call/4</seealso>,
-assuming that this is a record- or list-valued message() as documented
-in <seealso marker="diameter_app">diameter_app(3)</seealso>, and that
+assuming that this is a record- or list-valued <seealso
+marker="diameter_app#message">diameter_app:message()</seealso>, and that
 the message contains at most one of each AVP.
-If this is not the case then the <c>{host|realm, DiameterIdentity()}</c>
+If this is not the case then the <c>{host|realm, <seealso
+marker="diameter_dict#DATA_TYPES">DiameterIdentity()</seealso>}</c>
 filters must be used to achieve the desired result.
 Note also that an empty host/realm (which should not be typical)
 is equivalent to an unspecified one for the purposes of filtering.</p>
@@ -568,9 +570,9 @@ following.</p>
 <tag><c>{down, Ref, Peer, Config}</c></tag>
 <item>
 <code>
-Ref    = transport_ref()
-Peer   = diameter_app:peer()
-Config = {connect|listen, [transport_opt()]}
+Ref    = <seealso marker="#transport_ref">transport_ref()</seealso>
+Peer   = <seealso marker="diameter_app#peer">diameter_app:peer()</seealso>
+Config = {connect|listen, [<seealso marker="#transport_opt">transport_opt()</seealso>]}
 Pkt    = #diameter_packet{}
 </code>
 
@@ -587,8 +589,8 @@ connectivity.</p>
 <p>
 Note that a single up/down event for a given peer corresponds to
 as many <seealso marker="diameter_app#peer_up">peer_up/peer_down</seealso>
-callbacks as there are Diameter applications shared by the peer,
-as determined during capablilities exchange.
+callbacks as there are Diameter applications that have been negotiated
+during capablilities exchange.
 That is, the event communicates connectivity with the
 peer as a whole while the callbacks communicate connectivity with
 respect to individual Diameter applications.</p>
@@ -597,8 +599,8 @@ respect to individual Diameter applications.</p>
 <tag><c>{reconnect, Ref, Opts}</c></tag>
 <item>
 <code>
-Ref  = transport_ref()
-Opts = [transport_opt()]
+Ref  = <seealso marker="#transport_ref">transport_ref()</seealso>
+Opts = [<seealso marker="#transport_opt">transport_opt()</seealso>]
 </code>
 
 <p>
@@ -610,8 +612,8 @@ transport connection with a peer following <c>reconnect_timer</c> or
 <tag><c>{closed, Ref, Reason, Config}</c></tag>
 <item>
 <code>
-Ref = transport_ref()
-Config = {connect|listen, [transport_opt()]}
+Ref = <seealso marker="#transport_ref">transport_ref()</seealso>
+Config = {connect|listen, [<seealso marker="#transport_opt">transport_opt()</seealso>]}
 </code>
 
 <p>
@@ -627,7 +629,7 @@ Result = ResultCode | {capabilities_cb, CB, ResultCode|discard}
 Caps = #diameter_caps{}
 Pkt  = #diameter_packet{}
 ResultCode = integer()
-CB = evaluable()
+CB = <seealso marker="#evaluable">evaluable()</seealso>
 </code>
 
 <p>
@@ -732,12 +734,12 @@ that is somewhat unique.</p>
 <p>
 Options accepted by <seealso
 marker="#start_service">start_service/2</seealso>.
-Can be any <c>capability()</c> tuple as
+Can be any <seealso marker="#capability"><c>capability()</c></seealso> tuple as
 well as the following.</p>
 
 <taglist>
 
-<tag><c>{application, [application_opt()]}</c></tag>
+<tag><c>{application, [<seealso marker="#application_opt">application_opt()</seealso>]}</c></tag>
 <item>
 <p>
 Defines a Diameter application supported by the service.</p>
@@ -746,7 +748,8 @@ Defines a Diameter application supported by the service.</p>
 A service must define one application for each Diameter application it
 intends to support.
 For an outgoing Diameter request, the application is specified by
-passing the desired application's <c>application_alias()</c> to
+passing the desired application's <seealso
+marker="#application_alias"><c>application_alias()</c></seealso> to
 <seealso marker="#call">call/4</seealso>, while for an
 incoming request the application identifier in the message
 header determines the application (and callback module), the
@@ -791,7 +794,7 @@ corresponding timeout (see <c>transport_config</c> below) or all fail.</p>
 </item>
 
 <tag><c>{transport_config, term()}</c></tag>
-<tag><c>{transport_config, term(), Unsigned32()}</c></tag>
+<tag><c>{transport_config, term(), <seealso marker="#diameter_dict#DATA_TYPES">Unsigned32()</seealso>}</c></tag>
 <item>
 <p>
 A term passed as the third argument to the <seealso
@@ -818,16 +821,18 @@ request a connection with one peer over SCTP or another
 To listen on both SCTP and TCP, define one transport for each.</p>
 </item>
 
-<tag><c>{applications, [application_alias()]}</c></tag>
+<tag><c>{applications, [<seealso marker="#application_alias">application_alias()</seealso>]}</c></tag>
 <item>
 <p>
 The list of Diameter applications to which usage of the transport
 should be restricted.
 Defaults to all applications configured on the service
-in question.</p>
+in question.
+Must only specify applications defined on the service to which
+the transport is added.</p>
 </item>
 
-<tag><c>{capabilities, [capability()]}</c></tag>
+<tag><c>{capabilities, [<seealso marker="#capability">capability()</seealso>]}</c></tag>
 <item>
 <p>
 AVP's used to construct outgoing CER/CEA messages.
@@ -843,7 +848,7 @@ not over SCTP as implemented by
 <seealso marker="diameter_sctp">diameter_sctp(3)</seealso>.</p>
 </item>
 
-<tag><c>{capabilities_cb, evaluable()}</c></tag>
+<tag><c>{capabilities_cb, <seealso marker="#evaluable">evaluable()</seealso>}</c></tag>
 <item>
 <p>
 A callback invoked upon reception of CER/CEA during capabilities
@@ -871,7 +876,7 @@ case the corresponding callbacks are applied until either all return
 <tag><c>{watchdog_timer, TwInit}</c></tag>
 <item>
 <code>
-TwInit = Unsigned32()
+TwInit = <seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>
        | {M,F,A}
 </code>
 
@@ -892,7 +897,7 @@ Defaults to 30000 if unspecified.</p>
 <tag><c>{reconnect_timer, Tc}</c></tag>
 <item>
 <code>
-Tc = Unsigned32()
+Tc = <seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>
 </code>
 
 <p>
@@ -911,11 +916,12 @@ causing the RFC 3539 state machine to pass to state OPEN rather than
 REOPEN.
 Note that these semantics are not goverened by the RFC and
 that a listening transport's reconnect_timer should be greater than its
-peers's Tc plus jitter.</p>
+peer's Tc plus jitter.</p>
 
 <p>
 Defaults to 30000 for a connecting transport and 60000 for a listening
 transport.</p>
+
 </item>
 
 </taglist>
@@ -927,6 +933,15 @@ marker="#service_info">service_info/2</seealso> and can be referred to
 in predicate functions passed to <seealso
 marker="#remove_transport">remove_transport/2</seealso>.</p>
 
+<marker id="transport_ref"/>
+</item>
+
+<tag><c>transport_ref() = reference()</c></tag>
+<item>
+<p>
+An reference returned by <seealso
+marker="#add_transport">add_transport/2</seealso> that
+identifies the configuration.</p>
 </item>
 
 </taglist>
@@ -943,9 +958,9 @@ marker="#remove_transport">remove_transport/2</seealso>.</p>
         -> {ok, Ref} | {error, Reason}</name>
 <fsummary>Add transport capability to a service.</fsummary>
 <type>
-<v>SvcName = service_name()</v>
-<v>Options = [transport_opt()]</v>
-<v>Ref = ref()</v>
+<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
+<v>Options = [<seealso marker="#transport_opt">transport_opt()</seealso>]</v>
+<v>Ref = <seealso marker="#transport_ref">transport_ref()</seealso></v>
 <v>Reason = term()</v>
 </type>
 <desc>
@@ -953,8 +968,8 @@ marker="#remove_transport">remove_transport/2</seealso>.</p>
 Add transport capability to a service.</p>
 
 <p>
-The service will start a transport process(es) in order to establish a
-connection with the peer, either by connecting to the peer
+The service will start transport processes as required in order to
+establish a connection with the peer, either by connecting to the peer
 (<c>connect</c>) or by  accepting incoming connection requests
 (<c>listen</c>).
 A connecting transport establishes transport connections with at most
@@ -990,11 +1005,11 @@ transports.</p>
 <name>call(SvcName, App, Request, Options) -> ok | Answer | {error, Reason}</name>
 <fsummary>Send a Diameter request message.</fsummary>
 <type>
-<v>SvcName = service_name()</v>
-<v>App = application_alias()</v>
-<v>Request = diameter_app:message() | term()</v>
+<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
+<v>App = <seealso marker="#application_alias">application_alias()</seealso></v>
+<v>Request = <seealso marker="diameter_app#message">diameter_app:message()</seealso></v>
 <v>Answer = term()</v>
-<v>Options = [call_opt()]</v>
+<v>Options = [<seealso marker="#call_opt">call_opt()</seealso>]</v>
 </type>
 <desc>
 <p>
@@ -1112,7 +1127,7 @@ transport.</p>
 <!-- ===================================================================== -->
 
 <func>
-<name>origin_state_id() -> Unsigned32()</name>
+<name>origin_state_id() -> <seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso></name>
 <fsummary>Returns a reasonable Origin-State-Id.</fsummary>
 <desc>
 <p>
@@ -1121,7 +1136,7 @@ outgoing messages.</p>
 
 <p>
 The value returned is the number of seconds since 19680120T031408Z,
-the first value that can be encoded as a Diameter Time(),
+the first value that can be encoded as a Diameter <seealso marker="diameter_dict#DATA_TYPES">Time()</seealso>,
 at the time the diameter application was started.</p>
 
 <marker id="remove_transport"/>
@@ -1134,11 +1149,11 @@ at the time the diameter application was started.</p>
 <name>remove_transport(SvcName, Pred) -> ok</name>
 <fsummary>Remove previously added transports.</fsummary>
 <type>
-<v>SvcName = service_name()</v>
-<v>Pred = Fun | MFA | ref() | list() | true | false</v>
+<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
+<v>Pred = Fun | MFA | <seealso marker="#transport_ref">transport_ref()</seealso> | list() | true | false</v>
 <v></v>
-<v>Fun = fun((reference(), connect|listen, list()) -> boolean())</v>
-<v>&nbsp;&nbsp;&nbsp; | fun((reference(), list()) -> boolean())</v>
+<v>Fun = fun((<seealso marker="#transport_ref">transport_ref()</seealso>, connect|listen, list()) -> boolean())</v>
+<v>&nbsp;&nbsp;&nbsp; | fun((<seealso marker="#transport_ref">transport_ref()</seealso>, list()) -> boolean())</v>
 <v>&nbsp;&nbsp;&nbsp; | fun((list()) -> boolean())</v>
 <v>MFA = {atom(), atom(), list()}</v>
 </type>
@@ -1156,12 +1171,12 @@ as returned by the corresponding call.
 The remaining forms are equivalent to an arity-3 fun as follows.</p>
 
 <code>
-Pred = fun(reference(), list()):  fun(Ref, _, Opts) -> Pred(Ref, Opts) end
-Pred = fun(list()):               fun(_, _, Opts) -> Pred(Opts) end
-Pred = reference():               fun(Ref, _, _)  -> Pred == Ref end
-Pred = list():                    fun(_, _, Opts) -> [] == Pred -- Opts end
-Pred = true:                      fun(_, _, _) -> true end
-Pred = false:                     fun(_, _, _) -> false end
+Pred = fun(transport_ref(), list()):  fun(Ref, _, Opts) -> Pred(Ref, Opts) end
+Pred = fun(list()):                   fun(_, _, Opts) -> Pred(Opts) end
+Pred = transport_ref():               fun(Ref, _, _)  -> Pred == Ref end
+Pred = list():                        fun(_, _, Opts) -> [] == Pred -- Opts end
+Pred = true:                          fun(_, _, _) -> true end
+Pred = false:                         fun(_, _, _) -> false end
 Pred = {M,F,A}:  fun(Ref, Type, Opts) -> apply(M, F, [Ref, Type, Opts | A]) end
 </code>
 
@@ -1186,7 +1201,7 @@ DPA or timeout.</p>
 <name>service_info(SvcName, Item) -> Value</name>
 <fsummary>Return specific information about a started service.</fsummary>
 <type>
-<v>SvcName = service_name()</v>
+<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
 <v>Value = term()</v>
 </type>
 <desc>
@@ -1203,7 +1218,7 @@ Return information about a started service.</p>
 <name>services() -> [SvcName]</name>
 <fsummary>Return the list of started services.</fsummary>
 <type>
-<v>SvcName = service_name()</v>
+<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
 </type>
 <desc>
 <p>
@@ -1216,10 +1231,10 @@ Return the list of started services.</p>
 <!-- ===================================================================== -->
 
 <func>
-<name>session_id(Ident) -> OctetString()</name>
+<name>session_id(Ident) -> <seealso marker="diameter_dict#DATA_TYPES">OctetString()</seealso></name>
 <fsummary>Return a value for a Session-Id AVP.</fsummary>
 <type>
-<v>Ident = DiameterIdentity()</v>
+<v>Ident = <seealso marker="diameter_dict#DATA_TYPES">DiameterIdentity()</seealso></v>
 </type>
 <desc>
 <p>
@@ -1244,7 +1259,7 @@ Start the diameter application.</p>
 
 <p>
 The diameter application must be started before starting a service.
-In a production system this will typically be accomplished by a boot
+In a production system this is typically accomplished by a boot
 file, not by calling <c>start/0</c> explicitly.</p>
 
 <marker id="start_service"/>
@@ -1256,8 +1271,8 @@ file, not by calling <c>start/0</c> explicitly.</p>
 <name>start_service(SvcName, Options) -> ok | {error, Reason}</name>
 <fsummary>Start a Diameter service.</fsummary>
 <type>
-<v>SvcName = service_name()</v>
-<v>Options = [service_opt()]</v>
+<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
+<v>Options = [<seealso marker="#service_opt">service_opt()</seealso>]</v>
 <v>Reason  = term()</v>
 </type>
 <desc>
@@ -1265,11 +1280,20 @@ file, not by calling <c>start/0</c> explicitly.</p>
 Start a diameter service.</p>
 
 <p>
-A service defines a locally-implemented Diameter peer, specifying the
-capabilities of the peer to be used during capabilities exchange and
+A service defines a locally-implemented Diameter node, specifying the
+capabilities of the node to be used during capabilities exchange and
 the Diameter applications that it supports.
 Transports are added to a service using <seealso
-marker="#add_transport">add_transport/2</seealso>.</p>
+marker="#add_transport">add_transport/2</seealso>.
+</p>
+
+<note>
+<p>
+A transport can both override its service's
+capabilities and restrict its supported Diameter applications so
+"service = Diameter node as identified by Origin-Host" is not
+necessarily the case.</p>
+</note>
 
 <marker id="stop_service"/>
 </desc>
@@ -1295,7 +1319,7 @@ Stop the diameter application.</p>
 <name>stop_service(SvcName) -> ok | {error, Reason}</name>
 <fsummary>Stop a Diameter service.</fsummary>
 <type>
-<v>SvcName = service_name()</v>
+<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
 <v>Reason = term()</v>
 </type>
 <desc>
@@ -1312,15 +1336,19 @@ Stop a diameter service.</p>
 <name>subscribe(SvcName) -> true</name>
 <fsummary>Subscribe to event messages.</fsummary>
 <type>
-<v>SvcName = service_name()</v>
+<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
 </type>
 <desc>
 <p>
-Subscribe to <c>service_event()</c> messages from a service.</p>
+Subscribe to <seealso
+marker="#service_event"><c>service_event()</c></seealso> messages from
+a service.</p>
 
 <p>
 It is not an error to subscribe to events from a service
-that does not yet exist.</p>
+that does not yet exist.
+Doing so before adding transports is required to guarantee the
+reception of all related events.</p>
 
 <marker id="unsubscribe"/>
 </desc>
@@ -1332,7 +1360,7 @@ that does not yet exist.</p>
 <name>unsubscribe(SvcName) -> true</name>
 <fsummary>Unsubscribe to event messages.</fsummary>
 <type>
-<v>SvcName = service_name()</v>
+<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
 </type>
 <desc>
 <p>
diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml
index a786443fa1..6e5c957eec 100644
--- a/lib/diameter/doc/src/diameter_app.xml
+++ b/lib/diameter/doc/src/diameter_app.xml
@@ -45,8 +45,8 @@ A diameter service as started by <seealso
 marker="diameter#start_service">diameter:start_service/2</seealso>
 configures one of more Diameter applications, each of whose
 configuration specifies a callback that handles messages specific to
-its application.
-The messages and AVPs of the Diameter application are defined in a
+the application.
+The messages and AVPs of the application are defined in a
 dictionary file whose format is documented in
 <seealso marker="diameter_dict">diameter_dict(4)</seealso>
 while the callback module is documented here.
@@ -106,11 +106,13 @@ and, for the call-specific callbacks, any extra arguments passed to
 
 <taglist>
 
+<marker id="capabilities"/>
+
 <tag><c>capabilities() = #diameter_caps{}</c></tag>
 <item>
 <p>
 A record containing the identities of
-the local and remote Diameter peers having an established transport
+the local Diameter node and the remote Diameter peer having an established transport
 connection, as well as the capabilities as
 determined by capabilities exchange.
 Each field of the record is a 2-tuple consisting of
@@ -119,6 +121,8 @@ Optional or possibly multiple values are encoded as lists of values,
 mandatory values as the bare value.</p>
 </item>
 
+<marker id="message"/>
+
 <tag><c>message() = record() | list()</c></tag>
 <item>
 <p>
@@ -149,6 +153,8 @@ are sent exactly as specified.</p>
 
 </item>
 
+<marker id="packet"/>
+
 <tag><c>packet() = #diameter_packet{}</c></tag>
 <item>
 <p>
@@ -158,6 +164,8 @@ Fields of a packet() record should not be set in return values except
 as documented.</p>
 </item>
 
+<marker id="peer_ref"/>
+
 <tag><c>peer_ref() = term()</c></tag>
 <item>
 <p>
@@ -165,12 +173,16 @@ A term identifying a transport connection with a Diameter peer.
 Should be treated opaquely.</p>
 </item>
 
-<tag><c>peer() = {peer_ref(), capabilities()}</c></tag>
+<marker id="peer"/>
+
+<tag><c>peer() = {<seealso marker="#peer_ref">peer_ref()</seealso>, <seealso marker="#capabilities">capabilities()</seealso>}</c></tag>
 <item>
 <p>
 A tuple representing a Diameter peer connection.</p>
 </item>
 
+<marker id="service_name"/>
+
 <tag><c>service_name() = term()</c></tag>
 <item>
 <p>
@@ -180,6 +192,8 @@ marker="diameter#start_service">diameter:start_service/2</seealso>
 when starting the service.</p>
 </item>
 
+<marker id="state"/>
+
 <tag><c>state() = term()</c></tag>
 <item>
 <p>
@@ -211,9 +225,9 @@ process.</p>
 <name>Mod:peer_up(SvcName, Peer, State) -> NewState</name>
 <fsummary>Invoked when a transport connection has been established</fsummary>
 <type>
-<v>SvcName = service_name()</v>
-<v>Peer    = peer()</v>
-<v>State   = NewState = state()</v>
+<v>SvcName = <seealso marker="service_name">#service_name()</seealso></v>
+<v>Peer    = <seealso marker="#peer">peer()</seealso></v>
+<v>State   = NewState = <seealso marker="#state">state()</seealso></v>
 </type>
 <desc>
 <p>
@@ -230,9 +244,9 @@ the callback module in question has been configured.</p>
 <name>Mod:peer_down(SvcName, Peer, State) -> NewState</name>
 <fsummary>Invoked when a transport connection has been lost.</fsummary>
 <type>
-<v>SvcName = service_name()</v>
-<v>Peer    = peer()</v>
-<v>State   = NewState = state()</v>
+<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
+<v>Peer    = <seealso marker="#peer">peer()</seealso></v>
+<v>State   = NewState = <seealso marker="#state">state()</seealso></v>
 </type>
 <desc>
 <p>
@@ -248,10 +262,10 @@ call to <seealso marker="#peer_up">peer_up/3</seealso>.</p>
       -> {ok, Peer} | {Peer, NewState} | false</name>
 <fsummary>Select a target peer for an outgoing request.</fsummary>
 <type>
-<v>Candidates = [peer()]</v>
-<v>Peer = peer() | false</v>
-<v>SvcName = service_name()</v>
-<v>State = NewState = state()</v>
+<v>Candidates = [<seealso marker="#peer">peer()</seealso>]</v>
+<v>Peer = <seealso marker="#peer">peer()</seealso> | false</v>
+<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
+<v>State = NewState = <seealso marker="#state">state()</seealso></v>
 </type>
 <desc>
 <p>
@@ -278,7 +292,8 @@ equivalent when callback state is mutable, as are
 <c>{ok, Peer}</c> and <c>{Peer, State}</c>.
 Returning a peer as <c>false</c> causes <c>{error, no_connection}</c>
 to be returned from <seealso marker="diameter#call">diameter:call/4</seealso>.
-Returning a peer() from an initial pick_peer/4 callback will result in a
+Returning a <seealso marker="#peer">peer()</seealso> from an initial
+pick_peer/4 callback will result in a
 <seealso marker="#prepare_request">prepare_request/3</seealso> callback
 followed by either <seealso
 marker="#handle_answer">handle_answer/4</seealso>
@@ -301,9 +316,9 @@ received from a previously selected peer.</p>
 <p>
 <c>{Peer, NewState}</c> and its equivalents can only be returned if
 the Diameter application in question was
-configured with the option <c>{call_mutates_state, true}</c>,
-as documented for <seealso
-marker="diameter#start_service">diameter:start_service/2</seealso>.
+configured with the <seealso
+marker="diameter#application_opt">diameter:application_opt()</seealso>
+<c>{call_mutates_state, true}</c>.
 Otherwise, the <c>State</c> argument is always
 the intial value as configured on the application, not any subsequent
 value returned by a <seealso marker="#peer_up">peer_up/3</seealso>
@@ -319,10 +334,10 @@ or <seealso marker="#peer_down">peer_down/3</seealso> callback.</p>
 <name>Mod:prepare_request(Packet, SvcName, Peer) -> Action</name>
 <fsummary>Return a request for encoding and transport.</fsummary>
 <type>
-<v>Packet = packet()</v>
-<v>SvcName = service_name()</v>
-<v>Peer = peer()</v>
-<v>Action = {send, packet() | message()} | {discard, Reason} | discard</v>
+<v>Packet = <seealso marker="#packet">packet()</seealso></v>
+<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
+<v>Peer = <seealso marker="#peer">peer()</seealso></v>
+<v>Action = {send, <seealso marker="#packet">packet()</seealso> | <seealso marker="#message">message()</seealso>} | {discard, Reason} | discard</v>
 </type>
 <desc>
 <p>
@@ -334,13 +349,13 @@ callback need not be limited to this usage.
 Many implementations may simply want to return <c>{send, Packet}</c></p>
 
 <p>
-A returned packet() should set the request to be encoded in its
+A returned <seealso marker="#packet">packet()</seealso> should set the request to be encoded in its
 <c>msg</c> field and can set the <c>transport_data</c> field in order
 to pass information to the transport module.
 Extra arguments passed to <seealso
 marker="diameter#call">diameter:call/4</seealso> can be used to
 communicate transport data to the callback.
-A returned packet() can also set the <c>header</c> field to a
+A returned <seealso marker="#packet">packet()</seealso> can also set the <c>header</c> field to a
 <c>diameter_header</c> record in order to specify values that should
 be preserved in the outgoing request, although this should typically
 not be necessary and allows the callback to set header values
@@ -364,10 +379,10 @@ discarded}</c>.</p>
 <name>Mod:prepare_retransmit(Packet, SvcName, Peer) -> Result</name>
 <fsummary>Return a request for encoding and retransmission.</fsummary>
 <type>
-<v>Packet  = packet()</v>
-<v>SvcName = service_name()</v>
-<v>Peer    = peer()</v>
-<v>Result  = {send, packet() | message()} | {discard, Reason} | discard</v>
+<v>Packet  = <seealso marker="#packet">packet()</seealso></v>
+<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
+<v>Peer    = <seealso marker="#peer">peer()</seealso></v>
+<v>Result  = {send, <seealso marker="#packet">packet()</seealso> | <seealso marker="#message">message()</seealso>} | {discard, Reason} | discard</v>
 </type>
 <desc>
 <p>
@@ -375,7 +390,7 @@ Invoked to return a request for encoding and retransmission.
 Has the same role as <seealso
 marker="#prepare_request">prepare_request/3</seealso> in the case that
 a peer connection is lost an an alternate peer selected but the
-argument packet() is as returned by the initial
+argument <seealso marker="#packet">packet()</seealso> is as returned by the initial
 <c>prepare_request/3</c>.</p>
 
 <p>
@@ -394,10 +409,10 @@ discarded}</c>.</p>
 <name>Mod:handle_answer(Packet, Request, SvcName, Peer) -> Result</name>
 <fsummary>Receive an answer message from a peer.</fsummary>
 <type>
-<v>Packet  = packet()</v>
-<v>Request = message()</v>
-<v>SvcName = service_name()</v>
-<v>Peer    = peer()</v>
+<v>Packet  = <seealso marker="#packet">packet()</seealso></v>
+<v>Request = <seealso marker="#message">message()</seealso></v>
+<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
+<v>Peer    = <seealso marker="#peer">peer()</seealso></v>
 <v>Result  = term()</v>
 </type>
 <desc>
@@ -410,7 +425,7 @@ specified.</p>
 
 <p>
 The decoded answer record is in the <c>msg</c> field of the argument
-packet(),
+<seealso marker="#packet">packet()</seealso>,
 the undecoded binary in the <c>packet</c> field.
 <c>Request</c> is the outgoing request message as was returned from
 <seealso marker="#prepare_request">prepare_request/3</seealso> or
@@ -447,9 +462,9 @@ marker="diameter#start_service">diameter:start_service/2</seealso>.</p>
 <fsummary>Return an error from a outgoing request.</fsummary>
 <type>
 <v>Reason  = timeout | failover | term()</v>
-<v>Request = message()</v>
-<v>SvcName = service_name()</v>
-<v>Peer    = peer()</v>
+<v>Request = <seealso marker="#message">message()</seealso></v>
+<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
+<v>Peer    = <seealso marker="#peer">peer()</seealso></v>
 <v>Result  = term()</v>
 </type>
 <desc>
@@ -478,14 +493,14 @@ callback returned false.</p>
 <name>Mod:handle_request(Packet, SvcName, Peer) -> Action</name>
 <fsummary>Receive an incoming request.</fsummary>
 <type>
-<v>Packet  = packet()</v>
+<v>Packet  = <seealso marker="#packet">packet()</seealso></v>
 <v>SvcName = term()</v>
-<v>Peer    = peer()</v>
+<v>Peer    = <seealso marker="#peer">peer()</seealso></v>
 <v>Action  = Reply | {relay, Opts} | discard | {eval, Action, PostF}</v>
-<v>Reply   = {reply, message()}
+<v>Reply   = {reply, <seealso marker="#message">message()</seealso>}
            | {protocol_error, 3000..3999}</v>
-<v>Opts    = diameter:call_opts()</v>
-<v>PostF   = diameter:evaluable()</v>
+<v>Opts    = <seealso marker="diameter#call opts">diameter:call_opts()</seealso></v>
+<v>PostF   = <seealso marker="diameter#evaluable">diameter:evaluable()</seealso></v>
 </type>
 <desc>
 <p>
@@ -501,13 +516,13 @@ itself as defining either the application in question or the Relay
 application.</p>
 
 <p>
-The argument packet() has the following signature.</p>
+The argument <seealso marker="#packet">packet()</seealso> has the following signature.</p>
 
 <code>
 #diameter_packet{header = #diameter_header{},
                  avps   = [#diameter_avp{}],
                  msg    = record() | undefined,
-                 errors = ['Unsigned32'() | {'Unsigned32'(), #diameter_avp{}}],
+                 errors = [<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso> | {<seealso marker="#diameter_dict#DATA_TYPES">Unsigned32()</seealso>, #diameter_avp{}}],
                  bin    = binary(),
                  transport_data = term()}
 </code>
@@ -524,8 +539,8 @@ The <c>errors</c> field specifies any Result-Code's identifying errors
 that were encountered in decoding the request.
 In this case diameter will set both Result-Code and
 Failed-AVP AVP's in a returned
-answer message() before sending it to the peer:
-the returned message() need only set any other required AVP's.
+answer <seealso marker="#message">message()</seealso> before sending it to the peer:
+the returned <seealso marker="#message">message()</seealso> need only set any other required AVP's.
 Note that the errors detected by diameter are all of the 5xxx series
 (Permanent Failures).
 The <c>errors</c> list is empty if the request has been received in
@@ -535,7 +550,7 @@ the relay application.</p>
 The <c>transport_data</c> field contains an arbitrary term passed into
 diameter from the transport module in question, or the atom
 <c>undefined</c> if the transport specified no data.
-The term is preserved in the packet() containing any answer message
+The term is preserved in the <seealso marker="#packet">packet()</seealso> containing any answer message
 sent back to the transport process unless another value is explicitly
 specified.</p>
 
@@ -544,7 +559,7 @@ The semantics of each of the possible return values are as follows.</p>
 
 <taglist>
 
-<tag><c>{reply, message()}</c></tag>
+<tag><c>{reply, <seealso marker="#message">message()</seealso>}</c></tag>
 <item>
 <p>
 Send the specified answer message to the peer.</p>
diff --git a/lib/diameter/doc/src/diameter_sctp.xml b/lib/diameter/doc/src/diameter_sctp.xml
index c1e839b8e1..03e2f1f6be 100644
--- a/lib/diameter/doc/src/diameter_sctp.xml
+++ b/lib/diameter/doc/src/diameter_sctp.xml
@@ -58,11 +58,11 @@ and implements the behaviour documented in
 <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>Opt = {raddr, ip_address()} | {rport, integer()} | term()</v>
+<v>Opt = {raddr, inet:ip_address()} | {rport, integer()} | term()</v>
 <v>Pid = pid()</v>
-<v>LAddr = ip_address()</v>
+<v>LAddr = inet:ip_address()</v>
 <v>Reason = term()</v>
 </type>
 <desc>
diff --git a/lib/diameter/doc/src/diameter_tcp.xml b/lib/diameter/doc/src/diameter_tcp.xml
index e6b53383c0..6ad98c8640 100644
--- a/lib/diameter/doc/src/diameter_tcp.xml
+++ b/lib/diameter/doc/src/diameter_tcp.xml
@@ -65,13 +65,13 @@ before configuring TLS capability on diameter transports.</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>Opt = OwnOpt | SslOpt | OtherOpt</v>
 <v>Pid = pid()</v>
-<v>LAddr = ip_address()</v>
+<v>LAddr = inet:ip_address()</v>
 <v>Reason = term()</v>
-<v>OwnOpt = {raddr, ip_address()}
+<v>OwnOpt = {raddr, inet:ip_address()}
           | {rport, integer()}
           | {port, integer()}</v>
 <v>SslOpt = {ssl_options, true | list()}</v>
@@ -123,7 +123,7 @@ 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 then the
+option <c>ip</c> is unspecified then the
 first of the service's addresses is used as the local address.</p>
 
 <p>
diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml
index 087a90b099..4ed02e3881 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 = [inet:ip_address()]</v>
 <v>Reason = term()</v>
 </type>
 <desc>