uri_string:percent_decode has incorrect return spec

[gabrieltholsgard]

Description
The function spec of uri_string:percent_decode/1 is not complete when it comes to the return values.
It is possible to get a return value of format {error, atom(), term()} as spec:ed by uri_string:raw_decode/1, which is called directly when a binary() or list() is passed as value to uri_string:percent_decode/1.
When handling this possible output Dialyzer will complain about not being able to match the output.

To Reproduce

In an erlang shell:

12> uri_string:percent_decode("foo%f2bar").
{error,invalid_utf8,<<"fooòbar">>}

-module(foo).

-export([bar/1]).

-spec bar(PercentText :: list() | binary()) -> {error, atom()} | list() | binary().
bar(PercentText) ->
   case uri_string:percent_decode(PercentText) of
      {error, Reason, _} -> {error, Reason};
      Result -> Result
   end.

When running dialyzer on module:

foo.erl:8:7: The pattern 
          {'error', Reason, _} can never match the type 
          binary() |
          maybe_improper_list(binary() |
                              maybe_improper_list(any(), binary() | []) |
                              byte(),
                              binary() | []) |
          {'error', {'invalid', {atom(), {_, _}}}} |
          #{'fragment' =>
                binary() |
                maybe_improper_list(binary() |
                                    maybe_improper_list(any(),
                                                        binary() | []) |
                                    char(),
                                    binary() | []),
            'host' =>
                binary() |
                maybe_improper_list(binary() |
                                    maybe_improper_list(any(),
                                                        binary() | []) |
                                    char(),
                                    binary() | []),
            'path' =>
                binary() |
                maybe_improper_list(binary() |
                                    maybe_improper_list(any(),
                                                        binary() | []) |
                                    char(),
                                    binary() | []),
            'port' => 'undefined' | non_neg_integer(),
            'query' =>
                binary() |
                maybe_improper_list(binary() |
                                    maybe_improper_list(any(),
                                                        binary() | []) |
                                    char(),
                                    binary() | []),
            'scheme' =>
                binary() |
                maybe_improper_list(binary() |
                                    maybe_improper_list(any(),
                                                        binary() | []) |
                                    char(),
                                    binary() | []),
            'userinfo' =>
                binary() |
                maybe_improper_list(binary() |
                                    maybe_improper_list(any(),
                                                        binary() | []) |
                                    char(),
                                    binary() | [])}

Expected behavior
I would expect that the potential return value {error, atom(), term()} is handled in some way, be it that percent_decode handles it and return a uniform error structure or that a secondary error structure is returned and the spec reflecting that, such that dialyzer stops complaining.
It can also be worth mentioning that same percent_decode may also throw an error if the input is binary.
For instance:

1> uri_string:percent_decode(<<"foo%f2bar">>).
** exception throw: {error,invalid_utf8,<<"fooòbar">>}
     in function  uri_string:check_utf8/1 (uri_string.erl, line 1575)

Affected versions
Erlang/OTP 26 [erts-14.2.5]
Running this version and have only checked on this version.

[u3s]

thanks for reporting the issue. your observations are correct. we will plan fixing it.