aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAnders Svensson <[email protected]>2013-10-10 10:47:45 +0200
committerAnders Svensson <[email protected]>2013-12-01 19:25:04 +0100
commit743773a87e24db2ba0f0222bcf4dcaba7ae7adcf (patch)
treed8ef4ef264513573ed43c239e91442b802259b05
parentb4b8a2130348d8828a53303d7003e24abfc692f2 (diff)
downloadotp-743773a87e24db2ba0f0222bcf4dcaba7ae7adcf.tar.gz
otp-743773a87e24db2ba0f0222bcf4dcaba7ae7adcf.tar.bz2
otp-743773a87e24db2ba0f0222bcf4dcaba7ae7adcf.zip
Document diameter_make:format/1 and diameter_make:flatten/1
-rw-r--r--lib/diameter/doc/src/diameter_make.xml78
-rw-r--r--lib/diameter/doc/src/seealso.ent2
2 files changed, 68 insertions, 12 deletions
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 -->