From 743773a87e24db2ba0f0222bcf4dcaba7ae7adcf Mon Sep 17 00:00:00 2001
From: Anders Svensson
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(-)
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.
-codec(File :: iolist() | binary(), [Opt]) -> ok | {ok, Ret} | {error, Reason}
+codec(File :: iolist() | binary(), [Opt]) -> ok
+ | {ok, [Out]}
+ | {error, Reason}
Compile a dictionary file into Erlang source.
-Compile a single dictionary file to Erlang source.
+Compile a single dictionary file.
The input File can be either a path or a literal dictionary,
the occurrence of newline (ascii NL) or carriage return (ascii CR)
identifying the latter.
-Opt can have the following types.
+Opt determines the format of the results and whether they are
+written to file or returned, and can have the following types.
+parse | forms | erl | hrl | beam
+-
+
+Specifies an output format.
+Whether the output is returned or written to file depends on whether
+or not option return is specified.
+When written to file, the resulting file(s) will have extensions
+.D, .F, .erl, .hrl and .beam
+respectively, basenames defaulting to dictionary if the input
+dictionary is literal and does not specify &dict_name;.
+When returned, results are returned in the Out list in the
+order specified.
+Format options default to erl and hrl (in this order) if
+unspecified.
+
+
+The parsed format is an internal representation that can be
+passed to &format; and &flatten;, while the forms format is
+only intended for debugging purposes.
+Output for the erl and hrl formats are returned as
+iolists, while the beam format returns a {module(),
+binary()} tuple.
+
+
+
{include, string()}
-
@@ -93,14 +122,15 @@ Multiple include options can be specified.
-
Write generated source to the specified directory.
-Defaults to the current working directory.
+Defaults to the current working directory.
+Has no effect if option return is specified.
return
-
-Return erl and hrl source as two iolists rather than writing them to
-the filesystem.
+Return results in a {ok, [Out]} tuple instead of writing to
+file and returning ok.
{name|prefix, string()}
@@ -118,7 +148,7 @@ Transform the input dictionary before compilation, appending
&dict_inherits; of the specified string.
-Two forms of @inherits have special meaning:
+Two forms have special meaning:
{inherits, "-"}
@@ -147,6 +177,34 @@ The &dict_name; of a literal input dictionary defaults to
+
+
+
+format(Parsed) -> iolist()
+Format a parsed dictionary.
+
+
+Turns a parsed dictionary, as returned by &codec;, back into the
+dictionary format.
+
+
+
+
+
+
+flatten(Parsed) -> term()
+Flatten a parsed dictionary.
+
+
+
+Reconstitute a parsed dictionary, as returned by &codec;, without
+using &dict_inherits;.
+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.
+
+
+
@@ -155,11 +213,7 @@ The &dict_name; of a literal input dictionary defaults to
BUGS
-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;
-
+Unrecognized options are silently ignored.
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:codec/2'>
+diameter_make:format/1'>
+diameter_make:flatten/1'>
--
cgit v1.2.3