Reformat documentation for hackney_url (#572)

A couple of things that I did here:

* Always use URL in place of url or Url.
* Use `an` article when referring to URL.
* Add link under normalize to pathencode.
* End a few sentences with a full stop, start with a capital letter.

Author: maciej-szlosarczyk

doc/hackney_url.md

@@ -6,7 +6,7 @@
 * [Function Index](#index)
 * [Function Details](#functions)
 
-module to manage urls.
+module to manage URLs.
 
 <a name="types"></a>
 
@@ -37,10 +37,8 @@ qs_vals() = [{binary(), binary() | true}]
 ## Function Index ##
 
 
-<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#fix_path-1">fix_path/1</a></td><td></td></tr><tr><td valign="top"><a href="#idnconvert_hostname-1">idnconvert_hostname/1</a></td><td></td></tr><tr><td valign="top"><a href="#make_url-3">make_url/3</a></td><td> construct an url from a base url, a path and a list of
-properties to give to the url.</td></tr><tr><td valign="top"><a href="#normalize-1">normalize/1</a></td><td>Normalizes the encoding of a Url
-use the hackney_url:pathencode/1 to encode an url.</td></tr><tr><td valign="top"><a href="#normalize-2">normalize/2</a></td><td>Normalizes the encoding of a Url.</td></tr><tr><td valign="top"><a href="#parse_qs-1">parse_qs/1</a></td><td></td></tr><tr><td valign="top"><a href="#parse_url-1">parse_url/1</a></td><td>Parse an url and return a #hackney_url record.</td></tr><tr><td valign="top"><a href="#pathencode-1">pathencode/1</a></td><td>encode a URL path.</td></tr><tr><td valign="top"><a href="#qs-1">qs/1</a></td><td>encode query properties to binary.</td></tr><tr><td valign="top"><a href="#qs-2">qs/2</a></td><td>encode query properties to binary
-Opts are passed to urlencode.</td></tr><tr><td valign="top"><a href="#transport_scheme-1">transport_scheme/1</a></td><td></td></tr><tr><td valign="top"><a href="#unparse_url-1">unparse_url/1</a></td><td></td></tr><tr><td valign="top"><a href="#urldecode-1">urldecode/1</a></td><td>Decode a URL encoded binary.</td></tr><tr><td valign="top"><a href="#urldecode-2">urldecode/2</a></td><td>Decode a URL encoded binary.</td></tr><tr><td valign="top"><a href="#urlencode-1">urlencode/1</a></td><td>URL encode a string binary.</td></tr><tr><td valign="top"><a href="#urlencode-2">urlencode/2</a></td><td>URL encode a string binary.</td></tr></table>
+<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#fix_path-1">fix_path/1</a></td><td></td></tr><tr><td valign="top"><a href="#idnconvert_hostname-1">idnconvert_hostname/1</a></td><td></td></tr><tr><td valign="top"><a href="#make_url-3">make_url/3</a></td><td>Construct an URL from a base URL, a path and a list of
+properties to give to the URL.</td></tr><tr><td valign="top"><a href="#normalize-1">normalize/1</a></td><td>Normalizes the encoding of an URL.</td></tr><tr><td valign="top"><a href="#normalize-2">normalize/2</a></td><td>Normalizes the encoding of an URL.</td></tr><tr><td valign="top"><a href="#parse_qs-1">parse_qs/1</a></td><td></td></tr><tr><td valign="top"><a href="#parse_url-1">parse_url/1</a></td><td>Parse an URL and return a #hackney_url record.</td></tr><tr><td valign="top"><a href="#pathencode-1">pathencode/1</a></td><td>Encode an URL path.</td></tr><tr><td valign="top"><a href="#qs-1">qs/1</a></td><td>Encode query properties to binary.</td></tr><tr><td valign="top"><a href="#qs-2">qs/2</a></td><td>Encode query properties to binary.</td></tr><tr><td valign="top"><a href="#transport_scheme-1">transport_scheme/1</a></td><td></td></tr><tr><td valign="top"><a href="#unparse_url-1">unparse_url/1</a></td><td></td></tr><tr><td valign="top"><a href="#urldecode-1">urldecode/1</a></td><td>Decode an URL encoded binary.</td></tr><tr><td valign="top"><a href="#urldecode-2">urldecode/2</a></td><td>Decode an URL encoded binary.</td></tr><tr><td valign="top"><a href="#urlencode-1">urlencode/1</a></td><td>URL encode a string binary.</td></tr><tr><td valign="top"><a href="#urlencode-2">urlencode/2</a></td><td>URL encode a string binary.</td></tr></table>
 
 
 <a name="functions"></a>
@@ -68,8 +66,8 @@ make_url(Url::binary(), Path::binary() | [binary()], Query::binary() | <a href="
 </code></pre>
 <br />
 
-construct an url from a base url, a path and a list of
-properties to give to the url.
+Construct an URL from a base URL, a path and a list of
+properties to give to the URL.
 
 <a name="normalize-1"></a>
 
@@ -81,8 +79,8 @@ normalize(URL) -&gt; NormalizedUrl
 
 <ul class="definitions"><li><code>URL = binary() | list() | <a href="#type-hackney_url">hackney_url()</a></code></li><li><code>NormalizedUrl = <a href="#type-hackney_url">hackney_url()</a></code></li></ul>
 
-Normalizes the encoding of a Url
-use the hackney_url:pathencode/1 to encode an url
+Normalizes the encoding of an URL.
+Use the [`hackney_url:pathencode/1`](hackney_url.md#pathencode-1) to encode an URL.
 
 <a name="normalize-2"></a>
 
@@ -94,7 +92,7 @@ normalize(URL, Fun) -&gt; NormalizedUrl
 
 <ul class="definitions"><li><code>URL = binary() | list() | <a href="#type-hackney_url">hackney_url()</a></code></li><li><code>Fun = function()</code></li><li><code>NormalizedUrl = <a href="#type-hackney_url">hackney_url()</a></code></li></ul>
 
-Normalizes the encoding of a Url
+Normalizes the encoding of an URL.
 
 <a name="parse_qs-1"></a>
 
@@ -114,7 +112,7 @@ parse_url(URL::binary() | list()) -&gt; <a href="#type-hackney_url">hackney_url(
 </code></pre>
 <br />
 
-Parse an url and return a #hackney_url record.
+Parse an URL and return a #hackney_url record.
 
 <a name="pathencode-1"></a>
 
@@ -127,7 +125,7 @@ pathencode(Bin::binary()) -&gt; binary()
 
 Equivalent to [`pathencode(Bin, [])`](#pathencode-2).
 
-encode a URL path
+Encode an URL path.
 
 <a name="qs-1"></a>
 
@@ -138,7 +136,7 @@ qs(KVs::<a href="#type-qs_vals">qs_vals()</a>) -&gt; binary()
 </code></pre>
 <br />
 
-encode query properties to binary
+Encode query properties to binary.
 
 <a name="qs-2"></a>
 
@@ -149,8 +147,8 @@ qs(KVs::<a href="#type-qs_vals">qs_vals()</a>, Opts::[<a href="#type-qs_opt">qs_
 </code></pre>
 <br />
 
-encode query properties to binary
-Opts are passed to urlencode.
+Encode query properties to binary.
+Opts are passed to [`urlencode/2`](#urlencode-2)
 
 <a name="transport_scheme-1"></a>
 
@@ -175,7 +173,7 @@ urldecode(Bin::binary()) -&gt; binary()
 
 Equivalent to [`urldecode(Bin, crash)`](#urldecode-2).
 
-Decode a URL encoded binary.
+Decode an URL encoded binary.
 
 <a name="urldecode-2"></a>
 
@@ -186,7 +184,7 @@ urldecode(Bin::binary(), OnError::crash | skip) -&gt; binary()
 </code></pre>
 <br />
 
-Decode a URL encoded binary.
+Decode an URL encoded binary.
 The second argument specifies how to handle percent characters that are not
 followed by two valid hex characters. Use `skip` to ignore such errors,
 if `crash` is used the function will fail with the reason `badarg`.

src/hackney_url.erl

@@ -7,7 +7,7 @@
 %%% Copyright (c) 2011, Magnus Klaar <[email protected]>
 %%%
 
-%% @doc module to manage urls.
+%% @doc module to manage URLs.
 
 -module(hackney_url).
 
@@ -30,7 +30,7 @@
 -type qs_vals() :: [{binary(), binary() | true}].
 -type qs_opt() :: noplus | upper.
 
-%% @doc Parse an url and return a #hackney_url record.
+%% @doc Parse an URL and return a #hackney_url record.
 -spec parse_url(URL::binary()|list()) -> hackney_url().
 parse_url(URL) when is_list(URL) ->
   case unicode:characters_to_binary(URL) of
@@ -63,15 +63,15 @@ parse_url(URL, S) ->
         fragment = Fragment})
   end.
 
-%% @doc Normalizes the encoding of a Url
-%% use the hackney_url:pathencode/1 to encode an url
+%% @doc Normalizes the encoding of an URL.
+%% Use the {@link hackney_url:pathencode/1} to encode an URL.
 -spec normalize(URL) -> NormalizedUrl when
   URL :: binary() | list() | hackney_url(),
   NormalizedUrl :: hackney_url().
 normalize(Url) ->
   normalize(Url, fun hackney_url:pathencode/1).
 
-%% @doc Normalizes the encoding of a Url
+%% @doc Normalizes the encoding of an URL.
 -spec normalize(URL, Fun) -> NormalizedUrl when
   URL :: binary() | list() | hackney_url(),
   Fun :: fun(),
@@ -256,13 +256,13 @@ parse_fragment(S) ->
   end.
 
 
-%% @doc Decode a URL encoded binary.
+%% @doc Decode an URL encoded binary.
 %% @equiv urldecode(Bin, crash)
 -spec urldecode(binary()) -> binary().
 urldecode(Bin) when is_binary(Bin) ->
   urldecode(Bin, <<>>, crash).
 
-%% @doc Decode a URL encoded binary.
+%% @doc Decode an URL encoded binary.
 %% The second argument specifies how to handle percent characters that are not
 %% followed by two valid hex characters. Use `skip' to ignore such errors,
 %% if `crash' is used the function will fail with the reason `badarg'.
@@ -341,7 +341,7 @@ tohexl(C) when C < 10 -> $0 + C;
 tohexl(C) when C < 16 -> $a + C - 10.
 
 
-%% parse a query or a form from a binary and return a list of properties
+%% Parse a query or a form from a binary and return a list of properties.
 -spec parse_qs(binary()) -> qs_vals().
 parse_qs(<<>>) ->
   [];
@@ -355,13 +355,13 @@ parse_qs(Bin) ->
    end || Token <- Tokens].
 
 
-%% @doc encode query properties to binary
+%% @doc Encode query properties to binary.
 -spec qs(qs_vals()) -> binary().
 qs(KVs) ->
   qs(KVs, []).
 
-%% @doc encode query properties to binary
-%% Opts are passed to urlencode.
+%% @doc Encode query properties to binary.
+%% Opts are passed to {@link urlencode/2.}
 -spec qs(qs_vals(), [qs_opt()]) -> binary().
 qs(KVs, Opts) ->
   qs(KVs, Opts, []).
@@ -374,8 +374,8 @@ qs([{K, V}|R], Opts, Acc) ->
   Line = << K1/binary, "=", V1/binary >>,
   qs(R, Opts, [Line | Acc]).
 
-%% @doc  construct an url from a base url, a path and a list of
-%% properties to give to the url.
+%% @doc Construct an URL from a base URL, a path and a list of
+%% properties to give to the URL.
 -spec make_url(binary(), binary() | [binary()], binary() | qs_vals())
     -> binary().
 make_url(Url, Path, Query) when is_list(Query) ->
@@ -409,7 +409,7 @@ fix_path(Path) ->
     _ -> Path
   end.
 
-%% @doc encode a URL path
+%% @doc Encode an URL path.
 %% @equiv pathencode(Bin, [])
 -spec pathencode(binary()) -> binary().
 pathencode(Bin) ->