Update uart driver with specs, types, and function documentation

Add type definitions for input parameters.
Add spec for all exported functions.
Add documentation for functions.

Signed-off-by: Winford <winford@object.stream>

Author: UncleGrumpy

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 with nodejs and emscripten)
 - Added preliminary support for ESP32P4 (no networking support yet).
 - Added memory info in `out_of_memory` crash logs to help developers fix memory issues.
+- Added documentation and function specs for uart driver
 
 ### Fixed
 

libs/eavmlib/src/uart.erl

@@ -21,24 +21,105 @@
 -module(uart).
 -export([open/1, open/2, close/1, read/1, write/2]).
 
+-type peripheral() :: string() | binary().
+% The peripheral `Name' may be one of: `"UART0"' | `"UART1"' | `"UART2"' | `<<"UART0">>' | `<<"UART1">>' | `<<"UART2">>'.
+
+-type uart_opts() :: [
+    {tx, Tx_pin :: integer()}
+    | {rx, Rx_pin :: integer()}
+    | {rts, Rts_pin :: integer()}
+    | {cts, Cts_pin :: integer()}
+    | {speed, Speed :: pos_integer()}
+    | {data_bits, 5..8}
+    | {stop_bits, 1 | 2}
+    | {event_queue_len, Qlen :: pos_integer()}
+    | {flow_control, none | hardware | software}
+    | {parity, none | even | odd}
+    | {peripheral, peripheral()}
+    | []
+].
+
+%%-----------------------------------------------------------------------------
+%% @param   Name the uart peripheral to be opened
+%% @param   Opts uart configuration options
+%% @returns Pid of the driver.
+%% @doc     Open a connection to the UART driver
+%%
+%%          This function will open a connection to the UART driver.
+%% @end
+%%-----------------------------------------------------------------------------
+-spec open(Name :: peripheral(), Opts :: uart_opts()) -> Pid :: pid() | {error, _Reason :: term()}.
 open(Name, Opts) ->
     open([{peripheral, Name} | Opts]).
 
+%%-----------------------------------------------------------------------------
+%% @param   Opts uart configuration options
+%% @returns Pid of the driver.
+%% @doc     Open a connection to the UART driver default port
+%%
+%%          This function will open a connection to the UART driver.
+%% @end
+%%-----------------------------------------------------------------------------
+-spec open(Opts :: uart_opts()) -> Pid :: pid() | {error, _Reason :: term()}.
 open(Opts) ->
     open_port({spawn, "uart"}, migrate_config(Opts)).
 
-close(Pid) ->
+%%-----------------------------------------------------------------------------
+%% @param   Pid of the uart port to be closed
+%% @returns ok.
+%% @doc     Close a port connection to the UART driver
+%%
+%%          This function will close the given port connection to the UART driver.
+%% @end
+%%-----------------------------------------------------------------------------
+-spec close(Pid :: pid()) -> ok | {error, _Reason :: term()}.
+close(Pid) when is_pid(Pid) ->
     port:call(Pid, close).
 
-read(Pid) ->
+%%-----------------------------------------------------------------------------
+%% @param   Pid of the uart port to be read
+%% @returns {ok, Data} or {error, Reason}
+%% @doc     Read data from a UART port
+%%
+%%          This function will return any data that is available, or return
+%%          a `{error, timeout}' tuple. The driver will sent the next available
+%%          data from the UART driver to the process that made the last read.
+%%          Example:
+%%          ```
+%%          Data = case uart:read(Uart) of
+%%              {ok, Binary} -> Binary;
+%%              {error, timeout} ->
+%%                  receive
+%%                      {ok, RecvBinary} -> RecvBinary;
+%%                      Error -> error(Error)
+%%                  end;
+%%              Error -> error(Error)
+%%          end,
+%%          '''
+%%          Any attempt by another (or the same process) to read from uart before the
+%%          next uart payload is sent by the driver will result in `{error, ealready}'.
+%% @end
+%%-----------------------------------------------------------------------------
+-spec read(Pid :: pid()) -> {ok, Data :: iodata()} | {error, _Reason :: term()}.
+read(Pid) when is_pid(Pid) ->
     port:call(Pid, read).
 
-write(Pid, B) ->
-    case is_iolist(B) of
+%%-----------------------------------------------------------------------------
+%% @param   Pid of the uart port to be written to
+%% @param   Data to be written to the given uart port
+%% @returns ok or {error, Reason}
+%% @doc     Write data to a UART port
+%%
+%%          This function will write the given data to the UART port.
+%% @end
+%%-----------------------------------------------------------------------------
+-spec write(Pid :: pid(), Data :: iodata()) -> ok | {error, _Reason :: term()}.
+write(Pid, Data) ->
+    case is_iolist(Data) andalso is_pid(Pid) of
         true ->
-            port:call(Pid, {write, B});
+            port:call(Pid, {write, Data});
         false ->
-            throw(badarg)
+            error(badarg)
     end.
 
 %% @private