Merge branch 'anders/diameter/doc/OTP-10471' into maint

* anders/diameter/doc/OTP-10471:
  Add missing diameter_codec(3) content
  Add content to diameter_codec(3) and diameter_make(3)
  Add reference pages diameter_codec(3) and diameter_make(3)

lib/diameter/doc/src/diameter.xml

@@ -1,5 +1,11 @@
 <?xml version="1.0" encoding="latin1" ?>
 <!DOCTYPE erlref SYSTEM "erlref.dtd" [
+  <!ENTITY make_ref
+  '<seealso marker="erts:erlang#make_ref-0">erlang:make_ref/0</seealso>'>
+  <!ENTITY transport_module
+  '<seealso marker="diameter_transport">transport module</seealso>'>
+  <!ENTITY dictionary
+  '<seealso marker="diameter_dict">dictionary</seealso>'>
   <!ENTITY % also SYSTEM "seealso.ent" >
   <!ENTITY % here SYSTEM "seehere.ent" >
   %also;
@@ -298,7 +304,7 @@ Has one of the following types.</p>
 <item>
 <p>
 An address list is available to the start function of a
-<seealso marker="diameter_transport">transport module</seealso>, which
+&transport_module;, which
 can return a new list for use in the subsequent CER or CEA.
 Host-IP-Address need not be specified if the transport start function
 returns an address list.</p>
@@ -464,7 +470,7 @@ that matches no peer.</p>
 <p>
 The <c>host</c> and <c>realm</c> filters examine the
 outgoing request as passed to &call;,
-assuming that this is a record- or list-valued <c>&app_message;</c>,
+assuming that this is a record- or list-valued <c>&codec_message;</c>,
 and that the message contains at most one of each AVP.
 If this is not the case then the <c>{host|realm, &dict_DiameterIdentity;}</c>
 filters must be used to achieve the desired result.
@@ -529,8 +535,7 @@ connectivity.</p>
 
 <p>
 Note that a single <c>up</c>/<c>down</c> event for a given peer
-corresponds to one
-<seealso marker="diameter_app#Mod:peer_up-3">peer_up/peer_down</seealso>
+corresponds to one &app_peer_up;/&app_peer_down;
 callback for each of the Diameter applications negotiated during
 capablilities exchange.
 That is, the event communicates connectivity with the
@@ -677,7 +682,7 @@ info fields of forms other than the above.</p>
 The name of a service as passed to &start_service; and with which the
 service is identified.
 There can be at most one service with a given name on a given node.
-Note that <seealso marker="erts:erlang#make_ref-0">erlang:make_ref/0</seealso>
+Note that &make_ref;
 can be used to generate a service name that is somewhat unique.</p>
 
 <marker id="service_opt"/>
@@ -703,8 +708,7 @@ For an outgoing Diameter request, the relevant <c>&application_alias;</c> is
 passed to &call;, while for an
 incoming request the application identifier in the message
 header determines the application, the identifier being specified in
-the application's <seealso marker="diameter_dict">dictionary</seealso>
-file.</p>
+the application's &dictionary; file.</p>
 </item>
 
 <tag><c>{restrict_connections, false
@@ -1125,7 +1129,7 @@ its transports.</p>
 <type>
 <v>SvcName = &service_name;</v>
 <v>App = &application_alias;</v>
-<v>Request = &app_message;</v>
+<v>Request = &codec_message;</v>
 <v>Answer = term()</v>
 <v>Opt = &call_opt;</v>
 </type>

lib/diameter/doc/src/diameter_app.xml

@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="latin1" ?>
 <!DOCTYPE erlref SYSTEM "erlref.dtd" [
+  <!ENTITY message '<seealso marker="#message">message()</seealso>'>
+  <!ENTITY dict
+  '<seealso marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>'>
   <!ENTITY % also SYSTEM "seealso.ent" >
   <!ENTITY % here SYSTEM "seehere.ent" >
   %also;
@@ -124,39 +127,17 @@ mandatory values as the bare value.</p>
 
 <marker id="message"/>
 
-<tag><c>message() = record() | list()</c></tag>
+<tag><c>message() = &codec_message;</c></tag>
 <item>
 <p>
 The representation of a Diameter message as passed to
-&mod_call;.
-The record representation is as outlined in
-<seealso
-marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>:
-a message as defined in a dictionary file is encoded as a record with
-one field for each component AVP.
-Equivalently, a message can also be encoded as a list whose head is
-the atom-valued message name (the record name minus any
-prefix specified in the relevant dictionary file) and whose tail is a
-list of <c>{FieldName, FieldValue}</c> pairs.</p>
-
-<p>
-A third representation allows a message to be specified as a list
-whose head is a <c>#diameter_header{}</c> record and whose tail is a list
-of <c>#diameter_avp{}</c> records.
-This representation is used by diameter itself when relaying requests
-as directed by the return value of a
-&handle_request;
-callback.
-It differs from the other other two in that it bypasses the checks for
-messages that do not agree with their definitions in the dictionary in
-question (since relays agents must handle arbitrary request): messages
-are sent exactly as specified.</p>
+&mod_call; or returned from a &handle_request; callback.</p>
 
 </item>
 
 <marker id="packet"/>
 
-<tag><c>packet() = #diameter_packet{}</c></tag>
+<tag><c>packet() = &codec_packet;</c></tag>
 <item>
 <p>
 A container for incoming and outgoing Diameter messages that's passed
@@ -505,8 +486,7 @@ The application in which the callback takes place (that is, the
 callback module as configured with &mod_start_service;)
 is determined by the Application Identifier in the header of the
 incoming request message, the selected module being the one
-whose corresponding <seealso
-marker="diameter_dict#MESSAGE_RECORDS">dictionary</seealso> declares
+whose corresponding dictionary declares
 itself as defining either the application in question or the Relay
 application.</p>
 
@@ -526,8 +506,7 @@ The argument &packet; has the following signature.</p>
 The <c>msg</c> field will be <c>undefined</c> in case the request has
 been received in the relay application.
 Otherwise it contains the record representing the request as outlined
-in <seealso
-marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>.</p>
+in &dict;.</p>
 
 <p>
 The <c>errors</c> field specifies any Result-Code's identifying errors