From 743773a87e24db2ba0f0222bcf4dcaba7ae7adcf Mon Sep 17 00:00:00 2001
From: Anders Svensson <anders@erlang.org>
Date: Thu, 10 Oct 2013 10:47:45 +0200
Subject: Document diameter_make:format/1 and diameter_make:flatten/1

---
 lib/diameter/doc/src/diameter_make.xml | 78 ++++++++++++++++++++++++++++------
 lib/diameter/doc/src/seealso.ent       |  2 +
 2 files changed, 68 insertions(+), 12 deletions(-)

(limited to 'lib/diameter/doc')

diff --git a/lib/diameter/doc/src/diameter_make.xml b/lib/diameter/doc/src/diameter_make.xml
index 2e69fca1ae..c8c0f2fbc7 100644
--- a/lib/diameter/doc/src/diameter_make.xml
+++ b/lib/diameter/doc/src/diameter_make.xml
@@ -64,19 +64,48 @@ interface.</p>
 <funcs>
 
 <func>
-<name>codec(File :: iolist() | binary(), [Opt]) -> ok | {ok, Ret} | {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.
+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> can have the following types.</p>
+<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 | beam</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>, <c>.hrl</c> and <c>.beam</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 returned in the <c>Out</c> list  in the
+order specified.
+Format options default to <c>erl</c> and <c>hrl</c> (in this order) if
+unspecified.</p>
+
+<p>
+The <c>parsed</c> format is an internal representation that can be
+passed to &format; and &flatten;, while the <c>forms</c> format is
+only intended for debugging purposes.
+Output for the <c>erl</c> and <c>hrl</c> formats are returned as
+iolists, while the <c>beam</c> format returns a <c>{module(),
+binary()}</c> tuple.</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>
@@ -93,14 +122,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 erl and hrl source as two iolists rather than writing them to
-the filesystem.</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>
@@ -118,7 +148,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, "-"}
@@ -147,6 +177,34 @@ The <c>&dict_name;</c> of a literal input dictionary defaults to
 </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>
+
 </funcs>
 
 <!-- ===================================================================== -->
@@ -155,11 +213,7 @@ The <c>&dict_name;</c> of a literal input dictionary defaults to
 <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 -->
 
-- 
cgit v1.2.3