From 27cfa1da6d35674f6cd169b103385a09c8d4c55a Mon Sep 17 00:00:00 2001
From: Luca Favatella <luca.favatella@erlang-solutions.com>
Date: Thu, 22 Feb 2018 20:14:18 +0000
Subject: inets: export types documented for http_uri module

Also:

* Reuse type `inet:port_number()` in `http_uri` code and doc;

* Do not imply that http_uri module can properly handle UTF-8 encoded
  binaries, while it can't.

* Enrich function specifications in http_uri module;

* Fix http_uri doc re missing type definition for `Scheme`.
---
 lib/inets/src/http_lib/http_uri.erl | 32 ++++++++++++++++++++++++++++----
 1 file changed, 28 insertions(+), 4 deletions(-)

(limited to 'lib/inets/src/http_lib')

diff --git a/lib/inets/src/http_lib/http_uri.erl b/lib/inets/src/http_lib/http_uri.erl
index 7f1ca02014..648bd0538a 100644
--- a/lib/inets/src/http_lib/http_uri.erl
+++ b/lib/inets/src/http_lib/http_uri.erl
@@ -61,16 +61,30 @@
 	 scheme_defaults/0, 
 	 encode/1, decode/1]).
 
--export_type([scheme/0, default_scheme_port_number/0]).
+-export_type([uri/0,
+              user_info/0,
+              scheme/0, default_scheme_port_number/0,
+              host/0,
+              path/0,
+              query/0,
+              fragment/0]).
 
+-type uri() :: string() | binary().
+-type user_info() :: string() | binary().
+-type scheme() :: atom().
+-type host() :: string() | binary().
+-type path() :: string() | binary().
+-type query() :: string() | binary().
+-type fragment() :: string() | binary().
+-type port_number() :: inet:port_number().
+-type default_scheme_port_number() :: port_number().
+-type hex_uri() :: string() | binary(). %% Hexadecimal encoded URI.
+-type maybe_hex_uri() :: string() | binary(). %% A possibly hexadecimal encoded URI.
 
 %%%=========================================================================
 %%%  API
 %%%=========================================================================
 
--type scheme() :: atom().
--type default_scheme_port_number() :: pos_integer().
-
 -spec scheme_defaults() ->
     [{scheme(), default_scheme_port_number()}].
 
@@ -82,9 +96,17 @@ scheme_defaults() ->
      {sftp,  22}, 
      {tftp,  69}].
 
+-type parse_result() ::
+        {scheme(), user_info(), host(), port_number(), path(), query()} |
+        {scheme(), user_info(), host(), port_number(), path(), query(),
+         fragment()}.
+
+-spec parse(uri()) -> {ok, parse_result()} | {error, term()}.
 parse(AbsURI) ->
     parse(AbsURI, []).
 
+-spec parse(uri(), [Option]) -> {ok, parse_result()} | {error, term()} when
+      Option :: {atom(), term()}.
 parse(AbsURI, Opts) ->
     case parse_scheme(AbsURI, Opts) of
 	{error, Reason} ->
@@ -105,6 +127,7 @@ reserved() ->
             $#, $[, $], $<, $>, $\", ${, $}, $|, %"
 			       $\\, $', $^, $%, $ ]).
 
+-spec encode(uri()) -> hex_uri().
 encode(URI) when is_list(URI) ->
     Reserved = reserved(), 
     lists:append([uri_encode(Char, Reserved) || Char <- URI]);
@@ -112,6 +135,7 @@ encode(URI) when is_binary(URI) ->
     Reserved = reserved(),
     << <<(uri_encode_binary(Char, Reserved))/binary>> || <<Char>> <= URI >>.
 
+-spec decode(maybe_hex_uri()) -> uri().
 decode(String) when is_list(String) ->
     do_decode(String);
 decode(String) when is_binary(String) ->
-- 
cgit v1.2.3