Merge pull request #11171 from kvakvs/doctest/xmerl/take2

[xmerl + doctest] Add some examples to exported functions

Author: lthor

lib/xmerl/src/xmerl.erl

@@ -154,6 +154,21 @@ A callback module can inherit definitions from other callback modules, through
 the required function `'#xml-interitance#'() -> [ModuleName::atom()]`.
 
 _See also:_ `export/2`, `export_simple/3`.
+
+## Examples
+
+```erlang
+1> {Element, []} = xmerl_scan:string("<greeting>hello</greeting>").
+2> lists:flatten(xmerl:export([Element], xmerl_xml, [])).
+"<?xml version=\"1.0\"?><greeting>hello</greeting>"
+```
+
+```erlang
+1> {Element, []} = xmerl_scan:string("<note><to>Tove</to><from>Jani</from></note>").
+2> Prolog = ["<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n"].
+3> lists:flatten(xmerl:export([Element], xmerl_xml, [{prolog, Prolog}])).
+"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<note><to>Tove</to><from>Jani</from></note>"
+```
 """.
 -spec export(Content, Callback, RootAttributes) ->
           ExportedFormat :: term() when
@@ -214,6 +229,13 @@ attributes. The XML-data is always converted to normal form before being passed
 to the callback module.
 
 _See also:_ `export/3`, `export_simple/2`.
+
+## Examples
+
+```erlang
+1> lists:flatten(xmerl:export_simple([{greeting, [], ["hello"]}], xmerl_xml, [])).
+"<?xml version=\"1.0\"?><greeting>hello</greeting>"
+```
 """.
 -spec export_simple(Content, Callback, RootAttributes) ->
           ExportedFormat :: term() when
@@ -242,7 +264,16 @@ export1(Content, Callbacks, RootAttrs) when is_list(Content) ->
     tagdef('#root#',1,[],Args,Callbacks).
 
 
--doc "Exports simple XML content directly, without further context.".
+-doc """
+Exports simple XML content directly, without further context.
+
+## Examples
+
+```erlang
+1> lists:flatten(xmerl:export_simple_content([{greeting, [], ["hello"]}], xmerl_xml)).
+"<greeting>hello</greeting>"
+```
+""".
 -spec export_simple_content(Content, Callback) -> _ when
       Content  :: [simple_element()],
       Callback :: callback().
@@ -255,6 +286,14 @@ export_simple_content(Content, Callbacks) when is_list(Callbacks) ->
 
 -doc """
 Export normal XML content directly, without further context.
+
+## Examples
+
+```erlang
+1> {Element, []} = xmerl_scan:string("<greeting>hello</greeting>").
+2> lists:flatten(xmerl:export_content([Element], [xmerl_xml])).
+"<greeting>hello</greeting>"
+```
 """.
 -spec export_content(Content, Callbacks) -> _ when
 	Content   :: [element()],
@@ -274,7 +313,16 @@ export_content([E | Es], Callbacks) ->
 export_content([], _Callbacks) ->
     [].
 
--doc "Export a simple XML element directly, without further context.".
+-doc """
+Export a simple XML element directly, without further context.
+
+## Examples
+
+```erlang
+1> lists:flatten(xmerl:export_simple_element({greeting, [], ["hello"]}, xmerl_xml)).
+"<greeting>hello</greeting>"
+```
+""".
 -spec export_simple_element(Element, Callback) -> _ when
 	Element  :: simple_element(),
 	Callback :: callback().
@@ -284,7 +332,17 @@ export_simple_element(Element, Callback) when is_atom(Callback) ->
 export_simple_element(Element, Callbacks) when is_list(Callbacks) ->
     export_element(xmerl_lib:expand_element(Element), Callbacks).
 
--doc "Exports a normal XML element directly, without further context.".
+-doc """
+Exports a normal XML element directly, without further context.
+
+## Examples
+
+```erlang
+1> {Element, []} = xmerl_scan:string("<greeting>hello</greeting>").
+2> lists:flatten(xmerl:export_element(Element, xmerl_xml)).
+"<greeting>hello</greeting>"
+```
+""".
 -spec export_element(Element, Callback) -> _ when
       Element  :: element(),
       Callback :: callback().
@@ -312,6 +370,14 @@ export_element(#xmlDecl{}, _CBs) ->
 
 -doc """
 For on-the-fly exporting during parsing (SAX style) of the XML document.
+
+## Examples
+
+```erlang
+1> {Element, []} = xmerl_scan:string("<empty/>").
+2> lists:flatten(xmerl:export_element(Element, xmerl_xml, state0)).
+"<empty/>"
+```
 """.
 -spec export_element(Element, Callback, CallbackState) ->
           ExportedFormat when
@@ -355,7 +421,16 @@ tagdef(Tag,Pos,Parents,Args,CBs) ->
     end.
 
 
--doc "Find the list of inherited callback modules for a given module.".
+-doc """
+Find the list of inherited callback modules for a given module.
+
+## Examples
+
+```erlang
+1> xmerl:callbacks(xmerl_xml).
+[xmerl_xml]
+```
+""".
 -spec callbacks(Module :: module()) -> [module()].
 callbacks(Module) ->
     Result = check_inheritance(Module, []),

lib/xmerl/src/xmerl_xpath.erl

@@ -126,6 +126,17 @@ Extracts the nodes from the parsed XML tree according the XPath `String`.
 
 `Scalar` is an `#xmlObj{}` record record with the fields `type` and `value`,
 where `#xmlObj.type` is `boolean | number | string`.
+
+## Examples
+
+```erlang
+1> Xml = "<root><item id=\"a\">one</item><item id=\"b\">two</item></root>".
+"<root><item id=\"a\">one</item><item id=\"b\">two</item></root>"
+2> {Doc, []} = xmerl_scan:string(Xml).
+...
+3> xmerl_xs:value_of(xmerl_xpath:string("/root/item[2]", Doc)).
+["two"]
+```
 """.
 -spec string(String, Node, Parents, Doc, Options) ->
           [nodeEntity()] | Scalar when

lib/xmerl/src/xmerl_xs.erl

@@ -69,13 +69,24 @@ Example, original XSLT:
 
 becomes in Erlang:
 
-```text
+```erlang
   template(E = #xmlElement{ parents=[{'doc',_}|_], name='title'}) ->
     ["<h1>",
      xslapply(fun template/1, E),
      "</h1>"];
 
 ```
+
+## Examples
+
+```erlang
+1> Xml = "<root><item>one</item><item>two</item></root>".
+"<root><item>one</item><item>two</item></root>"
+2> {Doc, []} = xmerl_scan:string(Xml).
+...
+3> xmerl_xs:xslapply(fun(E) -> xmerl_xs:value_of(E) end, xmerl_xs:select("/root/item", Doc)).
+[["one"],["two"]]
+```
 """.
 -spec xslapply(Fun, ElementList) -> io_lib:chars() when
       Fun         :: fun ((xmerl:element()) -> io_lib:chars() ),
@@ -108,6 +119,17 @@ becomes:
        value_of(select(".", E)), "</h1></div>"]
 
 ```
+
+## Examples
+
+```erlang
+1> Xml = "<root><item>one</item><item>two</item></root>".
+"<root><item>one</item><item>two</item></root>"
+2> {Doc, []} = xmerl_scan:string(Xml).
+...
+3> xmerl_xs:value_of(xmerl_xs:select("/root/item[2]", Doc)).
+["two"]
+```
 """.
 -spec value_of(E) -> io_lib:chars() when
       E :: xmerl:element() | [xmerl:element()].
@@ -125,6 +147,17 @@ Extract the nodes from the xml tree according to XPath.
 Equivalent to [`xmerl_xpath:string(Str, E)`](`xmerl_xpath:string/2`).
 
 _See also:_ `value_of/1`.
+
+## Examples
+
+```erlang
+1> Xml = "<root><item>one</item><item>two</item></root>".
+"<root><item>one</item><item>two</item></root>"
+2> {Doc, []} = xmerl_scan:string(Xml).
+...
+3> xmerl_xs:value_of(xmerl_xs:select("/root/item[2]", Doc)).
+["two"]
+```
 """.
 -spec select(String, E) -> Result when
       String  :: term(),
@@ -146,6 +179,19 @@ The default fallback behaviour.
 
 Template funs should end with:
 `template(E) -> built_in_rules(fun template/1, E)`.
+
+## Examples
+
+```erlang
+1> Xml = "<root><item>one</item></root>".
+"<root><item>one</item></root>"
+2> {Doc, []} = xmerl_scan:string(Xml).
+...
+3> [Text] = xmerl_xs:select("/root/item/text()", Doc).
+...
+4> xmerl_xs:built_in_rules(fun(_) -> [] end, Text).
+"one"
+```
 """.
 -spec built_in_rules(Fun, E :: xmerl:element()) -> io_lib:chars() when
       Fun :: fun ((xmerl:element()) -> io_lib:chars()).

lib/xmerl/test/xmerl_SUITE.erl

@@ -43,7 +43,8 @@
 %% Test groups
 %%----------------------------------------------------------------------
 all() ->
-    [{group, cpd_tests}, xpath_text1, xpath_main,
+    [doctests,
+     {group, cpd_tests}, xpath_text1, xpath_main,
      xpath_abbreviated_syntax, xpath_functions, xpath_namespaces,
      {group, misc}, {group, eventp_tests},
      {group, ticket_tests}, {group, app_test},
@@ -116,6 +117,12 @@ end_per_testcase(_Func,_Config) ->
 %%----------------------------------------------------------------------
 %% Test cases
 %%----------------------------------------------------------------------
+doctests(_Config) ->
+    Options = [{missing_tests, []}],
+    ok = ct_doctest:module(xmerl, Options),
+    ok = ct_doctest:module(xmerl_xpath, Options),
+    ok = ct_doctest:module(xmerl_xs, Options).
+
 cpd_invalid1(Config) ->
     file:set_cwd(datadir(Config)),
     case catch xmerl_scan:file(datadir_join(Config,[cpd,"cpd_test.xml"]),[]) of