stdlib: Update documentation (uri_string)

1 files changed, 38 insertions, 76 deletions

diff --git a/lib/stdlib/doc/src/uri_string.xml b/lib/stdlib/doc/src/uri_string.xml
index 8283b8ca0e..496573ae2f 100644
--- a/lib/stdlib/doc/src/uri_string.xml
+++ b/lib/stdlib/doc/src/uri_string.xml
@@ -24,7 +24,7 @@
     <title>maps</title>
     <prepared>Péter Dimitrov</prepared>
     <docno>1</docno>
-    <date>2017-08-23</date>
+    <date>2017-10-20</date>
     <rev>A</rev>
   </header>
   <module>uri_string</module>
@@ -34,7 +34,8 @@
     <p>A URI is an identifier consisting of a sequence of characters   matching the syntax
     rule named <em>URI</em> in <em>RFC 3986</em>.</p>
     <p>  The generic URI syntax consists of a hierarchical sequence of components referred
-    to as the scheme, authority, path, query, and fragment:<pre>
+    to as the scheme, authority, path, query, and fragment:</p>
+    <pre>
     URI         = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
     hier-part   = "//" authority path-abempty
                    / path-absolute
@@ -51,35 +52,26 @@
 
     unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
     </pre><br></br>
-    </p>
     <p>The interpretation of a URI depends only on the characters used and not on how those
     characters are represented in a network protocol.</p>
-    <p>The functions implemented by this module covers the following use cases:
+    <p>The functions implemented by this module covers the following use cases:</p>
     <list type="bulleted">
       <item>Parsing URIs<br></br>
       <c>parse/1</c></item>
       <item>Recomposing URIs<br></br>
       <c>recompose/2</c></item>
-      <item>Resolving URI references<br></br>
-      <c>resolve_uri_reference/3</c></item>
-      <item>Creating URI references<br></br>
-      <c>create_uri_reference/3</c></item>
-      <item>Normalizing URIs<br></br>
-      <c>normalize/1</c></item>
       <item>Transcoding URIs<br></br>
       <c>transcode/2</c></item>
-      <item>Working with urlencoded query strings<br></br>
-      <c>compose_query/1, dissect_query/1</c></item>
+      <item>Working with form-urlencoded query strings<br></br>
+      <c>compose_query/[1,2], dissect_query/1</c></item>
     </list>
-    </p>
-    <p>There are four different encodings present during the handling of URIs:
+    <p>There are four different encodings present during the handling of URIs:</p>
     <list type="bulleted">
       <item>Inbound binary encoding in binaries</item>
       <item>Inbound percent-encoding in lists and binaries</item>
       <item>Outbound binary encoding in binaries</item>
       <item>Outbound percent-encoding in lists and binaries</item>
     </list>
-    </p>
     <p>Unless otherwise specified the return value type and encoding are the same as the input
     type and encoding. That is, binary input returns binary output, list input returns a list
     output but mixed input returns list output. Input and output encodings are the same except
@@ -113,31 +105,34 @@
       <name name="compose_query" arity="1"/>
       <fsummary>Compose urlencoded query string.</fsummary>
       <desc>
-        <p>Composes an urlencoded <c><anno>QueryString</anno></c> based on a
+        <p>Composes a form-urlencoded <c><anno>QueryString</anno></c> based on a
 	<c><anno>QueryList</anno></c>, a list of unescaped key-value pairs.
 	Media type <c>application/x-www-form-urlencoded</c> is defined in section
-	8.2.1 of <c>RFC 1866</c> (HTML 2.0).
+	8.2.1 of <c>RFC 1866</c> (HTML 2.0). Reserved and unsafe characters, as
+	defined by RFC 1738 (Uniform Resource Locators), are procent-encoded.
 	</p>
-	<p>If an argument is invalid, a <c>badarg</c> exception is raised.</p>
         <p><em>Example:</em></p>
         <pre>
-1> <input>uri_string:compose_query(...).</input>
-</pre>
+1> <input>uri_string:compose_query([{"foo bar","1"},{"city","örebro"}]).</input>
+<![CDATA["foo+bar=1&amp;city=%C3%B6rebro"]]>
+	</pre>
       </desc>
     </func>
 
     <func>
-      <name name="create_uri_reference" arity="2"/>
-      <fsummary>Create references.</fsummary>
+      <name name="compose_query" arity="2"/>
+      <fsummary>Compose urlencoded query string.</fsummary>
       <desc>
-        <p>Creates an RFC 3986 compliant <c><anno>RelativeDestURI</anno></c>,
-	based <c><anno>AbsoluteSourceURI</anno></c> and <c><anno>AbsoluteSourceURI</anno></c>
-	</p>
-	<p>If an argument is invalid, a <c>badarg</c> exception is raised.</p>
+        <p>Same as <c>compose_query/1</c> but with an additional
+	<c><anno>Options</anno></c> parameter, that controls the type of separator used
+	between key-value pairs. There are two supported separator types: <c>amp</c> (<![CDATA[&amp;]]>)
+	and <c>semicolon</c> (;).</p>
         <p><em>Example:</em></p>
         <pre>
-1> <input>uri_string:create_uri_reference(...,...).</input>
-</pre>
+1> <input>uri_string:compose_query([{"foo bar","1"},{"city","örebro"}],</input>
+2> [{separator, semicolon}]).
+"foo+bar=1;city=%C3%B6rebro"
+	</pre>
       </desc>
     </func>
 
@@ -148,31 +143,14 @@
         <p>Dissects an urlencoded <c><anno>QueryString</anno></c> and returns a
 	<c><anno>QueryList</anno></c>, a list of unescaped key-value pairs.
 	Media type <c>application/x-www-form-urlencoded</c> is defined in section
-	8.2.1 of <c>RFC 1866</c> (HTML 2.0).
+	8.2.1 of <c>RFC 1866</c> (HTML 2.0). Percent-encoded segments are decoded
+	as defined by RFC 1738 (Uniform Resource Locators).
 	</p>
-	<p>If an argument is invalid, a <c>badarg</c> exception is raised.</p>
         <p><em>Example:</em></p>
         <pre>
-1> <input>uri_string:dissect_query(...).</input>
-</pre>
-      </desc>
-    </func>
-
-    <func>
-      <name name="normalize" arity="1"/>
-      <fsummary>Normalize URI.</fsummary>
-      <desc>
-        <p>Normalizes an RFC 3986 compliant <c><anno>URIString</anno></c> and returns
-	a <c><anno>NormalizedURI</anno></c>. The algorithm used to shorten the input
-	URI is called Syntax-Based Normalization and described at
-	<c>Section 6.2.2 of RFC 3986</c>.
-	</p>
-	<p>If an argument is invalid, a <c>badarg</c> exception is raised.</p>
-        <p><em>Example:</em></p>
-        <pre>
-1> <input>uri_string:normalize("http://example.org/one/two/../../one").</input>
-"http://example.org/one"
-</pre>
+1> <input>uri_string:dissect_query("foo+bar=1;city=%C3%B6rebro").</input>
+[{"foo bar","1"},{"city","örebro"}]
+	</pre>
       </desc>
     </func>
 
@@ -182,14 +160,14 @@
       <desc>
         <p>Returns a <c>URIMap</c>, that is a <em>uri_map()</em> with the parsed components
 	of the <c><anno>URIString</anno></c>.</p>
-        <p>If parsing fails, a <c>parse_error</c> exception is raised.</p>
+        <p>If parsing fails, an error tuple is returned.</p>
         <p><em>Example:</em></p>
         <pre>
 1> <input>uri_string:parse("foo://[email protected]:8042/over/there?name=ferret#nose").</input>
 #{fragment => "nose",host => "example.com",
   path => "/over/there",port => 8042,query => "name=ferret",
   scheme => foo,userinfo => "user"}
-2> </pre>
+	</pre>
       </desc>
     </func>
 
@@ -198,50 +176,34 @@
       <fsummary>Recompose URI.</fsummary>
       <desc>
         <p>Returns an RFC 3986 compliant <c><anno>URIString</anno></c> (percent-encoded).</p>
-	<p>If the <c><anno>URIMap</anno></c> is invalid, a <c>badarg</c> exception is raised.</p>
+	<p>If the <c><anno>URIMap</anno></c> is invalid, an error tuple is returned.</p>
         <p><em>Example:</em></p>
         <pre>
 1> <input>URIMap = #{fragment => "nose", host => "example.com", path => "/over/there",</input>
-port => 8042, query => "name=ferret", scheme => foo, userinfo => "user"}.
+port => 8042, query => "name=ferret", scheme => "foo", userinfo => "user"}.
 #{fragment => "top",host => "example.com",
   path => "/over/there",port => 8042,query => "?name=ferret",
   scheme => foo,userinfo => "user"}
 
-2> <input>uri_string:recompose(URIMap, []).</input>
+2> <input>uri_string:recompose(URIMap).</input>
 "foo://example.com:8042/over/there?name=ferret#nose"</pre>
       </desc>
     </func>
 
     <func>
-      <name name="resolve_uri_reference" arity="2"/>
-      <fsummary>Resolve URI reference.</fsummary>
-      <desc>
-        <p>Resolves an RFC 3986 compliant <c><anno>RelativeURI</anno></c>,
-	based <c><anno>AbsoluteBaseURI</anno></c> and returns a new absolute URI
-	(<c><anno>AbsoluteDestURI</anno></c>).</p>
-	<p>If an argument is invalid, a <c>badarg</c> exception is raised.</p>
-        <p><em>Example:</em></p>
-        <pre>
-1> <input>uri_string:resolve_uri_reference(...,...).</input>
-</pre>
-      </desc>
-    </func>
-
-    <func>
       <name name="transcode" arity="2"/>
       <fsummary>Transcode URI.</fsummary>
       <desc>
         <p>Transcodes an RFC 3986 compliant <c><anno>URIString</anno></c>,
 	where <c><anno>Options</anno></c> is a list of tagged tuples, specifying the inbound
 	(<c>in_encoding</c>) and outbound (<c>out_encoding</c>) encodings.</p>
-	<p>If an argument is invalid, a <c>badarg</c> exception is raised.</p>
+	<p>If an argument is invalid, an error tuple is returned.</p>
         <p><em>Example:</em></p>
         <pre>
-1> <input>uri_string:transcode(&lt;&lt;"foo://f%20oo"&gt;&gt;, [{in_encoding, utf8},</input>
-{out_encoding, utf16}]).
-&lt;&lt;0,102,0,111,0,111,0,58,0,47,0,47,0,102,0,37,0,48,0,48,0,37,0,50,0,48,0,
-  111,0,111&gt;&gt;
-</pre>
+1> <input><![CDATA[uri_string:transcode(<<"foo%00%00%00%F6bar"/utf32>>,]]></input>
+2> [{in_encoding, utf32},{out_encoding, utf8}]).
+<![CDATA[<<"foo%C3%B6bar"/utf8>>]]>
+	</pre>
       </desc>
     </func>