Merge branch 'anders/diameter/dictionary_make/OTP-11348' into maint

* anders/diameter/dictionary_make/OTP-11348:
  Return compilable forms instead of beam
  Document diameter_make:format/1 and diameter_make:flatten/1
  Fix diameter_make:flatten/1
  Modify type that currently causes dialyzer woe
  Simplify and extend diameter_make interface
  Add diameter_make:flatten/1, remove reformat/1
  Adapt compiler suite to diameter_make
  Remove dead code from codec suite
  Extend diameter_make:codec/2
  Don't pollute process dictionary in diameter_codegen:from_dict/4
  Make forms a separate output from diameter_codegen
  Remove last remnants of "spec"
  Write as last step in code generation
  Change extensions for debug output: .spec/forms -> .D/F

2 files changed, 84 insertions, 10 deletions

diff --git a/lib/diameter/doc/src/diameter_make.xml b/lib/diameter/doc/src/diameter_make.xml
index ec71251be1..68780b1e05 100644
--- a/lib/diameter/doc/src/diameter_make.xml
+++ b/lib/diameter/doc/src/diameter_make.xml
@@ -1,5 +1,7 @@
 <?xml version="1.0" encoding="latin1" ?>
 <!DOCTYPE erlref SYSTEM "erlref.dtd" [
+  <!ENTITY compile_forms2
+  '<seealso marker="compiler:compile#forms-2">compile:forms/2</seealso>'>
   <!ENTITY filename
   '<seealso marker="kernel:file#type-name">file:name()</seealso>'>
   <!ENTITY dictionary
@@ -64,16 +66,47 @@ interface.</p>
 <funcs>
 
 <func>
-<name>codec(Path::string(), [Opt]) -> ok | {error, Reason}</name>
+<name>codec(File :: iolist() | binary(), [Opt]) -> ok
+                                                 | {ok, [Out]}
+                                                 | {error, Reason}</name>
 <fsummary>Compile a dictionary file into Erlang source.</fsummary>
 <desc>
 
 <p>
-Compile a single dictionary file to Erlang source.
-<c>Opt</c> can have the following types.</p>
+Compile a single dictionary file.
+The input <c>File</c> can be either a path or a literal dictionary,
+the occurrence of newline (ascii NL) or carriage return (ascii CR)
+identifying the latter.
+<c>Opt</c> determines the format of the results and whether they are
+written to file or returned, and can have the following types.</p>
 
 <taglist>
 
+<tag><c>parse | forms | erl | hrl</c></tag>
+<item>
+<p>
+Specifies an output format.
+Whether the output is returned or written to file depends on whether
+or not option <c>return</c> is specified.
+When written to file, the resulting file(s) will have extensions
+<c>.D</c>, <c>.F</c>, <c>.erl</c>, and <c>.hrl</c>
+respectively, basenames defaulting to <c>dictionary</c> if the input
+dictionary is literal and does not specify <c>&dict_name;</c>.
+When returned, results are in the order of the corresponding format
+options.
+Format options default to <c>erl</c> and <c>hrl</c> (in this order) if
+unspecified.</p>
+
+<p>
+The <c>parse</c> format is an internal representation that can be
+passed to &flatten; and &format;, while the <c>forms</c> format can be
+passed to &compile_forms2;.
+The <c>erl</c> and <c>hrl</c> formats are returned as
+iolists.</p>
+<!-- That codec/2 can take the parsed format is undocumented, and
+     options name and inherits have no effect in this case. -->
+</item>
+
 <tag><c>{include, string()}</c></tag>
 <item>
 <p>
@@ -90,7 +123,15 @@ Multiple <c>include</c> options can be specified.</p>
 <item>
 <p>
 Write generated source to the specified directory.
-Defaults to the current working directory.</p>
+Defaults to the current working directory.
+Has no effect if option <c>return</c> is specified.</p>
+</item>
+
+<tag><c>return</c></tag>
+<item>
+<p>
+Return results in a <c>{ok, [Out]}</c> tuple instead of writing to
+file and returning <c>ok</c>.</p>
 </item>
 
 <tag><c>{name|prefix, string()}</c></tag>
@@ -108,7 +149,7 @@ Transform the input dictionary before compilation, appending
 <c>&dict_inherits;</c> of the specified string.</p>
 
 <p>
-Two forms of <c>@inherits</c> have special meaning:</p>
+Two forms have special meaning:</p>
 
 <pre>
 {inherits, "-"}
@@ -127,6 +168,41 @@ Multiple <c>inherits</c> options can be specified.</p>
 
 </taglist>
 
+<p>
+Note that a dictionary's <c>&dict_name;</c>, together with the
+<c>outdir</c> option, determine the output paths when the
+<c>return</c> option is not specified.
+The <c>&dict_name;</c> of a literal input dictionary defaults to
+<c>dictionary</c>.</p>
+
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+
+<func>
+<name>format(Parsed) -> iolist()</name>
+<fsummary>Format a parsed dictionary.</fsummary>
+<desc>
+<p>
+Turns a parsed dictionary, as returned by &codec;, back into the
+dictionary format.</p>
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+
+<func>
+<name>flatten(Parsed) -> term()</name>
+<fsummary>Flatten a parsed dictionary.</fsummary>
+<desc>
+
+<p>
+Reconstitute a parsed dictionary, as returned by &codec;, without
+using <c>&dict_inherits;</c>.
+That is, construct an equivalent dictionary in which all AVP's are
+definined in the dictionary itself.
+The return value is also a parsed dictionary.</p>
 </desc>
 </func>
 
@@ -138,11 +214,7 @@ Multiple <c>inherits</c> options can be specified.</p>
 <title>BUGS</title>
 
 <p>
-All options are string-valued.
-In particular, it is not currently possible to specify
-an &dict_inherits; module as an atom(), or a path as an arbitrary
-&filename;</p>
-
+Unrecognized options are silently ignored.</p>
 </section>
 
 <!-- ===================================================================== -->
diff --git a/lib/diameter/doc/src/seealso.ent b/lib/diameter/doc/src/seealso.ent
index 76b9823f79..d3305853af 100644
--- a/lib/diameter/doc/src/seealso.ent
+++ b/lib/diameter/doc/src/seealso.ent
@@ -115,6 +115,8 @@ significant.
 <!-- diameter_make -->
 
 <!ENTITY make_codec '<seealso marker="diameter_make#codec-2">diameter_make:codec/2</seealso>'>
+<!ENTITY make_format '<seealso marker="diameter_make#format-1">diameter_make:format/1</seealso>'>
+<!ENTITY make_flatten '<seealso marker="diameter_make#flatten-1">diameter_make:flatten/1</seealso>'>
 
 <!-- diameter_transport -->