Merge branch 'lars/xmerl-anchor-problems/OTP-13880' into maint

* lars/xmerl-anchor-problems/OTP-13880:
  [xmerl] Fix link problems in documentation

6 files changed, 120 insertions, 21 deletions

diff --git a/lib/xmerl/src/xmerl_eventp.erl b/lib/xmerl/src/xmerl_eventp.erl
index 2cb76abc6e..8d7ea25e24 100644
--- a/lib/xmerl/src/xmerl_eventp.erl
+++ b/lib/xmerl/src/xmerl_eventp.erl
@@ -25,6 +25,90 @@
 %% Each contain more elaborate settings of xmerl_scan that makes usage of
 %% the customization functions.
 %% 
+%% @type xmlElement() = #xmlElement{}.
+%%
+%% @type option_list(). <p>Options allow to customize the behaviour of the
+%%     scanner.
+%% See also <a href="xmerl_examples.html">tutorial</a> on customization
+%% functions.
+%% </p>
+%% <p>
+%% Possible options are:
+%% </p>
+%% <dl>
+%%  <dt><code>{acc_fun, Fun}</code></dt>
+%%    <dd>Call back function to accumulate contents of entity.</dd>
+%%  <dt><code>{continuation_fun, Fun} |
+%%            {continuation_fun, Fun, ContinuationState}</code></dt>
+%%    <dd>Call back function to decide what to do if the scanner runs into EOF
+%%     before the document is complete.</dd>
+%%  <dt><code>{event_fun, Fun} |
+%%            {event_fun, Fun, EventState}</code></dt>
+%%    <dd>Call back function to handle scanner events.</dd>
+%%  <dt><code>{fetch_fun, Fun} |
+%%            {fetch_fun, Fun, FetchState}</code></dt>
+%%    <dd>Call back function to fetch an external resource.</dd>
+%%  <dt><code>{hook_fun, Fun} |
+%%            {hook_fun, Fun, HookState}</code></dt>
+%%    <dd>Call back function to process the document entities once
+%%     identified.</dd>
+%%  <dt><code>{close_fun, Fun}</code></dt>
+%%    <dd>Called when document has been completely parsed.</dd>
+%%  <dt><code>{rules, ReadFun, WriteFun, RulesState} |
+%%            {rules, Rules}</code></dt>
+%%    <dd>Handles storing of scanner information when parsing.</dd>
+%%  <dt><code>{user_state, UserState}</code></dt>
+%%    <dd>Global state variable accessible from all customization functions</dd>
+%%
+%%  <dt><code>{fetch_path, PathList}</code></dt>
+%%    <dd>PathList is a list of
+%%     directories to search when fetching files. If the file in question
+%%     is not in the fetch_path, the URI will be used as a file
+%%     name.</dd>
+%%  <dt><code>{space, Flag}</code></dt>
+%%    <dd>'preserve' (default) to preserve spaces, 'normalize' to
+%%    accumulate consecutive whitespace and replace it with one space.</dd>
+%%  <dt><code>{line, Line}</code></dt>
+%%    <dd>To specify starting line for scanning in document which contains
+%%    fragments of XML.</dd>
+%%  <dt><code>{namespace_conformant, Flag}</code></dt>
+%%    <dd>Controls whether to behave as a namespace conformant XML parser,
+%%    'false' (default) to not otherwise 'true'.</dd>
+%%  <dt><code>{validation, Flag}</code></dt>
+%%    <dd>Controls whether to process as a validating XML parser:
+%%    'off' (default) no validation, or validation 'dtd' by DTD or 'schema'
+%%    by XML Schema. 'false' and 'true' options are obsolete
+%%    (i.e. they may be removed in a future release), if used 'false'
+%%    equals 'off' and 'true' equals 'dtd'.</dd>
+%%  <dt><code>{schemaLocation, [{Namespace,Link}|...]}</code></dt>
+%%    <dd>Tells explicitly which XML Schema documents to use to validate
+%%    the XML document. Used together with the
+%%    <code>{validation,schema}</code> option.</dd>
+%%  <dt><code>{quiet, Flag}</code></dt>
+%%    <dd>Set to 'true' if xmerl should behave quietly and not output any
+%%    information to standard output (default 'false').</dd>
+%%  <dt><code>{doctype_DTD, DTD}</code></dt>
+%%    <dd>Allows to specify DTD name when it isn't available in the XML
+%%    document. This option has effect only together with
+%%    <code>{validation,'dtd'</code> option.</dd>
+%%  <dt><code>{xmlbase, Dir}</code></dt>
+%%    <dd>XML Base directory. If using string/1 default is current directory.
+%%    If using file/1 default is directory of given file.</dd>
+%%  <dt><code>{encoding, Enc}</code></dt>
+%%    <dd>Set default character set used (default UTF-8).
+%%    This character set is used only if not explicitly given by the XML
+%%    declaration. </dd>
+%%  <dt><code>{document, Flag}</code></dt>
+%%    <dd>Set to 'true' if xmerl should return a complete XML document
+%%    as an xmlDocument record (default 'false').</dd>
+%%  <dt><code>{comments, Flag}</code></dt>
+%%    <dd>Set to 'false' if xmerl should skip comments otherwise they will
+%%    be returned as xmlComment records (default 'true').</dd>
+%%  <dt><code>{default_attrs, Flag}</code></dt>
+%%    <dd>Set to 'true' if xmerl should add to elements missing attributes
+%%    with a defined default value (default 'false').</dd>
+%% </dl> 
+%% 
 -module(xmerl_eventp).
 -vsn('0.19').
 -date('03-09-17').
diff --git a/lib/xmerl/src/xmerl_scan.erl b/lib/xmerl/src/xmerl_scan.erl
index 2147a46a13..5e0459ec21 100644
--- a/lib/xmerl/src/xmerl_scan.erl
+++ b/lib/xmerl/src/xmerl_scan.erl
@@ -111,13 +111,16 @@
 %%    <dd>Set to 'true' if xmerl should add to elements missing attributes
 %%    with a defined default value (default 'false').</dd>
 %% </dl>
+%% @type xmlElement() = #xmlElement{}.
+%% The record definition is found in xmerl.hrl.
+%% @type xmlDocument() = #xmlDocument{}.
+%% The record definition is found in xmerl.hrl.
 %% @type document() = xmlElement() | xmlDocument(). <p>
 %% The document returned by <tt>xmerl_scan:string/[1,2]</tt> and
 %% <tt>xmerl_scan:file/[1,2]</tt>. The type of the returned record depends on
 %% the value of the document option passed to the function.
 %% </p>
 
-
 -module(xmerl_scan).
 -vsn('0.20').
 -date('03-09-16').
diff --git a/lib/xmerl/src/xmerl_xpath.erl b/lib/xmerl/src/xmerl_xpath.erl
index bbebda1030..6146feba49 100644
--- a/lib/xmerl/src/xmerl_xpath.erl
+++ b/lib/xmerl/src/xmerl_xpath.erl
@@ -43,13 +43,27 @@
 %% </pre>
 %%
 %% @type nodeEntity() =
-%%      xmlElement()
-%%    | xmlAttribute()
-%%    | xmlText() 
-%%    | xmlPI()
-%%    | xmlComment()
-%%    | xmlNsNode()
-%%    | xmlDocument()
+%%      #xmlElement{}
+%%    | #xmlAttribute{}
+%%    | #xmlText{} 
+%%    | #xmlPI{}
+%%    | #xmlComment{}
+%%    | #xmlNsNode{}
+%%    | #xmlDocument{}
+%%
+%% @type docNodes() =   #xmlElement{}
+%%    | #xmlAttribute{}
+%%    | #xmlText{} 
+%%    | #xmlPI{}
+%%    | #xmlComment{}
+%%    | #xmlNsNode{}
+%%
+%% @type docEntity() =  #xmlDocument{} | [docNodes()]
+%%
+%% @type xPathString() = string()
+%%
+%% @type parentList() = [{atom(), integer()}]
+%%
 %% @type option_list(). <p>Options allows to customize the behaviour of the
 %%     XPath scanner.
 %% </p>
@@ -115,7 +129,7 @@ string(Str, Doc, Options) ->
 %%   Parents = parentList()
 %%   Doc     = nodeEntity()
 %%   Options = option_list()
-%%   Scalar  = xmlObj
+%%   Scalar  = #xmlObj{}
 %% @doc Extracts the nodes from the parsed XML tree according to XPath.
 %%   xmlObj is a record with fields type and value,
 %%   where type is boolean | number | string
diff --git a/lib/xmerl/src/xmerl_xs.erl b/lib/xmerl/src/xmerl_xs.erl
index 3e9f6622b8..1ce76cfa41 100644
--- a/lib/xmerl/src/xmerl_xs.erl
+++ b/lib/xmerl/src/xmerl_xs.erl
@@ -45,7 +45,6 @@
 %       XSLT package which is written i C++.
 % See also the <a href="xmerl_xs_examples.html">Tutorial</a>.
 %     </p>
-
 -module(xmerl_xs).
 
 -export([xslapply/2, value_of/1, select/2, built_in_rules/2 ]).
@@ -71,15 +70,13 @@
 %%    xslapply(fun template/1, E),
 %%    "&lt;/h1>"];
 %% </pre>
-
 xslapply(Fun, EList) when is_list(EList) ->
-    lists:map( Fun, EList);
+    lists:map(Fun, EList);
 xslapply(Fun, E = #xmlElement{})->
     lists:map( Fun, E#xmlElement.content).
 
-
 %% @spec value_of(E) -> List
-%%   E = unknown()
+%%   E = term()
 %%
 %% @doc Concatenates all text nodes within the tree.
 %%
diff --git a/lib/xmerl/src/xmerl_xsd.erl b/lib/xmerl/src/xmerl_xsd.erl
index 4b5efae8dd..a89b3159ec 100644
--- a/lib/xmerl/src/xmerl_xsd.erl
+++ b/lib/xmerl/src/xmerl_xsd.erl
@@ -49,6 +49,7 @@
 %%      <dd>It is possible by this option to provide a state with process
 %%          information from an earlier validation.</dd> 
 %% </dl>
+%% @type filename() = string()
 %% @end
 %%%-------------------------------------------------------------------
 -module(xmerl_xsd).
@@ -138,7 +139,7 @@ state2file(S=#xsd_state{schema_name=SN}) ->
 
 %% @spec state2file(State,FileName) -> ok | {error,Reason}
 %%       State = global_state()
-%%       FileName = filename()
+%%       FileName = string()
 %% @doc Saves the schema state with all information of the processed
 %% schema in a file. You can provide the file name for the saved
 %% state. FileName is saved with the <code>.xss</code> extension
@@ -153,7 +154,7 @@ state2file(S,FileName) when is_record(S,xsd_state) ->
 
 %% @spec file2state(FileName) -> {ok,State} | {error,Reason}
 %%       State = global_state()
-%%       FileName = filename()
+%%       FileName = string()
 %% @doc Reads the schema state with all information of the processed
 %% schema from a file created with <code>state2file/[1,2]</code>.  The
 %% format of this file is internal. The state can then be used
@@ -202,7 +203,7 @@ xmerl_xsd_vsn_check(S=#xsd_state{vsn=MD5_VSN}) ->
 process_validate(Schema,Xml) ->
     process_validate(Schema,Xml,[]).
 %% @spec process_validate(Schema,Element,Options) -> Result
-%%       Schema   = filename()
+%%       Schema   = string()
 %%       Element  = XmlElement
 %%       Options  = option_list()
 %%       Result   = {ValidXmlElement,State} | {error,Reason}
@@ -282,7 +283,7 @@ validate3(_,_,S) ->
 process_schema(Schema) ->
     process_schema(Schema,[]).
 %% @spec process_schema(Schema,Options) -> Result
-%%       Schema  = filename()
+%%       Schema  = string()
 %%       Result  = {ok,State} | {error,Reason}
 %%       State   = global_state()
 %%       Reason  = [ErrorReason] | ErrorReason
@@ -324,7 +325,7 @@ process_schema2({SE,_},State,_Schema) ->
 process_schemas(Schemas) ->
     process_schemas(Schemas,[]).
 %% @spec process_schemas(Schemas,Options) -> Result
-%%       Schemas  = [{NameSpace,filename()}|Schemas] | []
+%%       Schemas  = [{NameSpace,string()}|Schemas] | []
 %%       Result   = {ok,State} | {error,Reason}
 %%       Reason   = [ErrorReason] | ErrorReason
 %%       Options  = option_list()
@@ -5426,7 +5427,7 @@ add_key_once(Key,N,El,L) ->
 %%     {filename:join([[io_lib:format("/~w(~w)",[X,Y])||{X,Y}<-Parents],Type]),Pos}.
 
 %% @spec format_error(Errors) -> Result
-%%       Errors     = error_tuple() | [error_tuple()]
+%%       Errors     = tuple() | [tuple()]
 %%       Result       = string() | [string()]
 %% @doc Formats error descriptions to human readable strings.
 format_error(L) when is_list(L) -> 
diff --git a/lib/xmerl/vsn.mk b/lib/xmerl/vsn.mk
index a78a035a1f..95adaa5bb0 100644
--- a/lib/xmerl/vsn.mk
+++ b/lib/xmerl/vsn.mk
@@ -1 +1 @@
-XMERL_VSN = 1.3.11
+XMERL_VSN = 1.3.12