enhancing docs

Author: mjaric

lib/tds.ex

@@ -1,28 +1,82 @@
 defmodule Tds do
+  @moduledoc """
+  Microsoft SQL Server driver for Elixir.
+
+  Tds is partial implementation of the Micorosoft SQL Server
+  [MS-TDS](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-tds)
+  Tabular Data Stream Protocol.
+
+  A Tds query is performed in separate server-side prepare and execute stages.
+  At the moment query handle is not reused, but there is plan to cahce handles in
+  near feature. It uses [RPC](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-tds/619c43b6-9495-4a58-9e49-a4950db245b3)
+  requests by default to `Sp_Prepare` (ProcId=11) and `Sp_Execute` (ProcId=12)
+  query, but it is possible to configure driver to use only Sp_ExecuteSql.
+  Please consult with [configuration](readme.html#configuration) how to do this.
+  """
   alias Tds.Query
 
   @timeout 5000
   @execution_mode :prepare_execute
 
+  @type start_option ::
+          {:hostname, String.t()}
+          | {:port, :inet.port_number()}
+          | {:database, String.t()}
+          | {:username, String.t()}
+          | {:password, String.t()}
+          | {:timeout, timeout}
+          | {:connect_timeout, timeout}
+          | DBConnection.start_option()
+
+  @type isolation_level ::
+          :read_uncommitted
+          | :read_committed
+          | :repeatable_read
+          | :serializable
+          | :snapshot
+          | :no_change
+
+  @type conn :: DBConnection.conn()
+
+  @type resultset :: list(Tds.Result.t())
+
+  @type option :: DBConnection.option()
+
+  @type transaction_option ::
+          {:mode, :transaction | :savepoint}
+          | {:isolation_level, isolation_level()}
+          | option()
+
+  @type execute_option ::
+          {:decode_mapper, (list -> term)}
+          | {:resultset, boolean()}
+          | option
+
+  @spec start_link([start_option]) ::
+          {:ok, conn} | {:error, Tds.Error.t() | term}
   def start_link(opts \\ []) do
     DBConnection.start_link(Tds.Protocol, default(opts))
   end
 
-  def query(pid, statement, params, opts \\ []) do
+  @spec query(conn, iodata, list, [execute_option]) ::
+          {:ok, Tds.Result.t()} | {:error, Exception.t()}
+  def query(conn, statement, params, opts \\ []) do
     query = %Query{statement: statement}
     opts = Keyword.put_new(opts, :parameters, params)
 
-    case DBConnection.prepare_execute(pid, query, params, opts) do
+    case DBConnection.prepare_execute(conn, query, params, opts) do
       {:ok, _query, result} -> {:ok, result}
       {:error, err} -> {:error, err}
     end
   end
 
-  def query!(pid, statement, params, opts \\ []) do
+  @spec query!(conn, iodata, list, [execute_option]) ::
+          Tds.Result.t() | no_return()
+  def query!(conn, statement, params, opts \\ []) do
     query = %Query{statement: statement}
     opts = Keyword.put_new(opts, :parameters, params)
 
-    case DBConnection.prepare_execute(pid, query, params, opts) do
+    case DBConnection.prepare_execute(conn, query, params, opts) do
       {:ok, _query, result} -> result
       {:error, %{mssql: %{msg_text: msg}}} -> raise Tds.Error, msg
       {:error, err} -> raise err
@@ -33,76 +87,93 @@ defmodule Tds do
   Executes statement that can contain multiple sql batches, result will contain
   all results that server yield for each batch.
   """
-  def query_multi(pid, statemnt, params, opts \\ []) do
+  @spec query_multi(conn(), iodata(), option(), [execute_option]) ::
+          {:ok, resultset()}
+          | {:error, Exception.t()}
+  def query_multi(conn, statemnt, params, opts \\ []) do
     query = %Query{statement: statemnt}
 
     opts =
       opts
       |> Keyword.put_new(:parameters, params)
       |> Keyword.put_new(:resultset, true)
 
-    case DBConnection.prepare_execute(pid, query, params, opts) do
+    case DBConnection.prepare_execute(conn, query, params, opts) do
       {:ok, _query, resultset} -> {:ok, resultset}
       {:error, err} -> {:error, err}
     end
   end
 
-  def prepare(pid, statement, opts \\ []) do
+  @spec prepare(conn, iodata, [option]) ::
+          {:ok, Tds.Query.t()} | {:error, Exception.t()}
+  def prepare(conn, statement, opts \\ []) do
     query = %Query{statement: statement}
 
-    case DBConnection.prepare(pid, query, opts) do
+    case DBConnection.prepare(conn, query, opts) do
       {:ok, query} -> {:ok, query}
       {:error, err} -> {:error, err}
     end
   end
 
-  def prepare!(pid, statement, opts \\ []) do
+  @spec prepare!(conn, iodata, [option]) :: Tds.Query.t() | no_return()
+  def prepare!(conn, statement, opts \\ []) do
     query = %Query{statement: statement}
 
-    case DBConnection.prepare(pid, query, opts) do
+    case DBConnection.prepare(conn, query, opts) do
       {:ok, query} -> query
       {:error, %{mssql: %{msg_text: msg}}} -> raise Tds.Error, msg
       {:error, err} -> raise err
     end
   end
 
-  def execute(pid, query, params, opts \\ []) do
-    case DBConnection.execute(pid, query, params, opts) do
+  @spec execute(conn, Tds.Query.t(), list, [execute_option]) ::
+          {:ok, Tds.Query.t(), Tds.Result.t()}
+          | {:error, Tds.Error.t()}
+  def execute(conn, query, params, opts \\ []) do
+    case DBConnection.execute(conn, query, params, opts) do
       {:ok, q, result} -> {:ok, q, result}
       {:error, err} -> {:error, err}
     end
   end
 
-  def execute!(pid, query, params, opts \\ []) do
-    case DBConnection.execute(pid, query, params, opts) do
+  @spec execute!(conn, Tds.Query.t(), list, [execute_option]) ::
+          Tds.Result.t()
+  def execute!(conn, query, params, opts \\ []) do
+    case DBConnection.execute(conn, query, params, opts) do
       {:ok, _q, result} -> result
       {:error, %{mssql: %{msg_text: msg}}} -> raise Tds.Error, msg
       {:error, err} -> raise err
     end
   end
 
-  def close(pid, query, opts \\ []) do
-    case DBConnection.close(pid, query, opts) do
+  @spec close(conn, Tds.Query.t(), [option]) :: :ok | {:error, Exception.t()}
+  def close(conn, query, opts \\ []) do
+    case DBConnection.close(conn, query, opts) do
       {:ok, result} -> {:ok, result}
       {:error, err} -> {:error, err}
     end
   end
 
-  def close!(pid, query, opts \\ []) do
-    case DBConnection.close(pid, query, opts) do
+  @spec close!(conn, Tds.Query.t(), [option]) :: :ok
+  def close!(conn, query, opts \\ []) do
+    case DBConnection.close(conn, query, opts) do
       {:ok, result} -> result
       {:error, %{mssql: %{msg_text: msg}}} -> raise Tds.Error, msg
       {:error, err} -> raise err
     end
   end
 
-  def transaction(pid, fun, opts \\ []) do
-    DBConnection.transaction(pid, fun, opts)
+  @spec transaction(conn, (DBConnection.t() -> result), [transaction_option()]) ::
+          {:ok, result} | {:error, any}
+        when result: var
+  def transaction(conn, fun, opts \\ []) do
+    DBConnection.transaction(conn, fun, opts)
   end
 
   @spec rollback(DBConnection.t(), reason :: any) :: no_return
   defdelegate rollback(conn, any), to: DBConnection
 
+  @spec child_spec([start_option]) :: Supervisor.Spec.spec()
   def child_spec(opts) do
     DBConnection.child_spec(Tds.Protocol, default(opts))
   end