Changed the direct reference typenames to something more describing

src/esqlite3_nif.erl

@@ -1,3 +1,9 @@
+%% @author Maas-Maarten Zeeman <mmzeeman@xs4all.nl>
+%% @copyright 2011 - 2022 Maas-Maarten Zeeman
+%%
+%% @doc Low level Erlang API for sqlite3 databases.
+%% @end
+
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
 %% You may obtain a copy of the License at
@@ -9,11 +15,6 @@
 %% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 %% See the License for the specific language governing permissions and
 %% limitations under the License.
-%%
-%% @author Maas-Maarten Zeeman <mmzeeman@xs4all.nl>
-%% @copyright 2011 - 2022 Maas-Maarten Zeeman
-%%
-%% @doc Low level erlang API for sqlite3 databases.
 
 -module(esqlite3_nif).
 -author("Maas-Maarten Zeeman <mmzeeman@xs4all.nl>").
@@ -58,12 +59,20 @@
     status/2
 ]).
 
--type esqlite3() :: reference().
--type esqlite3_stmt() :: reference().
--type esqlite3_backup() :: reference().
--type sql() :: iodata(). 
+-type esqlite3_ref() :: reference().        % Reference to a database connection handle. See [https://sqlite.org/c3ref/sqlite3.html] for more details.
+-type esqlite3_stmt_ref() :: reference().   % Reference to a prepared statement object. See [https://sqlite.org/c3ref/stmt.html] for more details.
+-type esqlite3_backup_ref() :: reference(). % Reference to a online backup object. See [https://sqlite.org/c3ref/backup.html] for more details.
+-type sql() :: iodata().                % Make sure the iodata contains utf-8 encoded data.
+-type extended_errcode() :: integer().  % Extended sqlite3 error code. See [https://sqlite.org/rescode.html] for more details.
+-type error() :: {error, extended_errcode()}.
+-type error_info() :: #{ errcode := integer(),  
+                         extended_errcode := extended_errcode(),
+                         errstr := unicode:unicode_binary(),     % English-language text that describes the result code, as UTF-8
+                         errmsg := unicode:unicode_binary(),     % English-language text that describes the error, as UTF-8
+                         error_offset := integer()               % The byte offset to the token in the input sql.
+                       }.  % See: [https://sqlite.org/c3ref/errcode.html] for more information.
 
--export_type([esqlite3/0, esqlite3_stmt/0, esqlite3_backup/0, sql/0]).
+-export_type([esqlite3_ref/0, esqlite3_stmt_ref/0, esqlite3_backup_ref/0, sql/0, error/0, error_info/0]).
 
 -on_load(init/0).
 
@@ -76,27 +85,28 @@ init() ->
     ok = erlang:load_nif(NifFileName, 0).
 
 
-%% @doc Open the specified sqlite3 database.
-%%
--spec open(Filename) -> OpenResult
-    when Filename :: string(),
-         OpenResult :: {ok, esqlite3()} | {error, _}.
+%% @doc Open the specified sqlite3 database. 
+%%      It is possible to use sqlite's uri filenames to open files. 
+%%      See: [https://sqlite.org/uri.html] for more information.
+-spec open(Filename) -> OpenResult when
+      Filename :: string(),
+      OpenResult :: {ok, esqlite3_ref()} | error().
 open(_Filename) ->
     erlang:nif_error(nif_library_not_loaded).
 
 %% @doc Close the connection.
 %%
 -spec close(Connection) -> CloseResult
-    when Connection :: esqlite3(),
+    when Connection :: esqlite3_ref(),
          CloseResult :: ok | {error, _}.
 close(_Db) ->
     erlang:nif_error(nif_library_not_loaded).
 
 %% @doc Get an error messages for the last occurred error.
 %%
--spec error_info(Connection) -> ErrorMsg 
-    when Connection :: esqlite3(),
-         ErrorMsg :: map().
+-spec error_info(Connection) -> ErrorInfo 
+    when Connection :: esqlite3_ref(),
+         ErrorInfo :: error_info().
 error_info(_Db) ->
     erlang:nif_error(nif_library_not_loaded).
 
@@ -104,9 +114,9 @@ error_info(_Db) ->
 %% @doc Set an update hook
 %%
 -spec set_update_hook(Connection, Pid) -> Result
-    when Connection :: esqlite3(),
+    when Connection :: esqlite3_ref(),
          Pid :: pid(),
-         Result :: ok | {error, closed}.
+         Result :: ok.
 set_update_hook(_Db, _Pid) ->
     erlang:nif_error(nif_library_not_loaded).
 
@@ -114,7 +124,7 @@ set_update_hook(_Db, _Pid) ->
 %% @doc Execute a sql statement
 %%
 -spec exec(Connection, Sql) -> ExecResult 
-    when Connection :: esqlite3(),
+    when Connection :: esqlite3_ref(),
          Sql :: sql(),
          ExecResult :: ok | {error, _}.
 exec(_Connection, _Sql) ->
@@ -124,10 +134,10 @@ exec(_Connection, _Sql) ->
 %% @doc Compile a sql statement. 
 %%
 -spec prepare(Connection, Sql, PrepareFlags) -> PrepareResult
-    when Connection :: esqlite3(),
+    when Connection :: esqlite3_ref(),
          Sql :: sql(),
          PrepareFlags :: non_neg_integer(),
-         PrepareResult :: {ok, esqlite3_stmt()} | {error, _}.
+         PrepareResult :: {ok, esqlite3_stmt_ref()} | {error, _}.
 prepare(_Connection, _Sql, _PrepareFlags) ->
     erlang:nif_error(nif_library_not_loaded).
 
@@ -157,13 +167,13 @@ reset(_Statement) ->
 
 %% @doc Retrieve the column names of the prepared statement
 %%
--spec column_names(esqlite3_stmt()) -> list(binary()) | {error, _}.
+-spec column_names(esqlite3_stmt_ref()) -> list(binary()) | {error, _}.
 column_names(_Stmt) ->
     erlang:nif_error(nif_library_not_loaded).
 
 %% @doc Retrieve the declared datatypes of all columns.
 %%
--spec column_decltypes(esqlite3_stmt()) -> list(undefined | binary()) | {error, _}.
+-spec column_decltypes(esqlite3_stmt_ref()) -> list(undefined | binary()) | {error, _}.
 column_decltypes(_Stmt) ->
     erlang:nif_error(nif_library_not_loaded).
 
@@ -171,11 +181,11 @@ column_decltypes(_Stmt) ->
 %% @doc Initialize a backup procedure of a database.
 %    erlang:nif_error(nif_library_not_loaded).
 -spec backup_init(Destination, DestinationName, Source, SourceName) -> InitResult when
-      Destination :: esqlite3(),
+      Destination :: esqlite3_ref(),
       DestinationName :: iodata(),
-      Source :: esqlite3(),
+      Source :: esqlite3_ref(),
       SourceName :: iodata(),
-      InitResult :: {ok, esqlite3_backup()} | {error, _}.
+      InitResult :: {ok, esqlite3_backup_ref()} | {error, _}.
 backup_init(_Dest, _DestName, _Src, _SrcName) ->
     erlang:nif_error(nif_library_not_loaded).
 
@@ -193,26 +203,26 @@ backup_finish(_Backup) ->
     erlang:nif_error(nif_library_not_loaded).
 
 %% @doc Interrupt all active queries.
--spec interrupt(esqlite3()) -> ok.
+-spec interrupt(esqlite3_ref()) -> ok.
 interrupt(_Db) ->
     erlang:nif_error(nif_library_not_loaded).
 
 %% @doc Get the last insert rowid.
 %%
--spec last_insert_rowid(esqlite3()) -> integer() | {error, _}.
+-spec last_insert_rowid(esqlite3_ref()) -> integer().
 last_insert_rowid(_Connection) ->
     erlang:nif_error(nif_library_not_loaded).
 
 %% @doc Get number of changes insert, delete of the most recent completed
 %%      INSERT, DELETE or UPDATE statement.
 %%
--spec changes(esqlite3()) -> integer() | {error, _}.
+-spec changes(esqlite3_ref()) -> integer().
 changes(_Connection) ->
     erlang:nif_error(nif_library_not_loaded).
 
 %% @doc Get autocommit
 %%
--spec get_autocommit(esqlite3()) -> true | false | {error, _}.
+-spec get_autocommit(esqlite3_ref()) -> true | false.
 get_autocommit(_Connection) ->
     erlang:nif_error(nif_library_not_loaded).
 
@@ -226,6 +236,7 @@ memory_stats(_Flag) ->
 
 %% @doc Get sqlite status information.
 %%
+%% <code>
 %% MEMORY_USED        0
 %% PAGECACHE_USED     1
 %% PAGECACHE_OVERFLOW 2
@@ -233,6 +244,7 @@ memory_stats(_Flag) ->
 %% PARSER_STACK       6
 %% PAGECACHE_SIZE     7
 %% MALLOC_COUNT       8
+%% </code>
 %%
 -spec status(Op, HighwaterResetFlag) -> Stats when 
       Op :: integer(),