Improving documentation

.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: mix
+    directory: "/"
+    schedule:
+      interval: daily
+      time: "02:00"
+    open-pull-requests-limit: 10

.github/workflows/hex-deploy.yml

@@ -39,8 +39,15 @@ jobs:
         run: mix local.hex --force && mix local.rebar --force
       - name: Install dependencies
         run: mix deps.get
-      - name: Set the new version
-        run: mix version.up
+      - name: Set the new patch version
+        if: "contains(github.event.head_commit.message, '[patch]')"
+        run: mix version.up patch
+      - name: Set the new minor version
+        if: "contains(github.event.head_commit.message, '[minor]')"
+        run: mix version.up minor
+      - name: Set the new major version
+        if: "contains(github.event.head_commit.message, '[major]')"
+        run: mix version.up major
       - name: Publish to hex.pm
         run: HEX_API_KEY=${{ secrets.HEX_API_KEY }} mix hex.publish --yes
       - name: Tag the version

README.md

@@ -232,6 +232,10 @@ config :ravix, Ravix.Test.Store,
   certificate_file: "/opt/certs/cert.pfx"
 ```
 
+## Ecto
+
+What about querying your RavenDB using Ecto? [Ravix-Ecto](https://github.com/YgorCastor/ravix-ecto)
+
 ## Current State
 
 * ~~Configuration Reading~~

lib/connection/commands/get_topology.ex

@@ -3,7 +3,7 @@ defmodule Ravix.Connection.Commands.GetTopology do
   Command to fetch the topology data from RavenDB
 
   ## Fields
-  - database_name: The name of the database 
+  - database_name: The name of the database
   - force_url: Forces the informed url to the new topology
   """
   use Ravix.Documents.Commands.RavenCommand,

lib/connection/connection.ex

@@ -1,7 +1,5 @@
 defmodule Ravix.Connection do
-  @moduledoc """
-     Service to manage the connection with a RavenDB database
-  """
+  @moduledoc false
   use GenServer
 
   require OK
@@ -16,7 +14,7 @@ defmodule Ravix.Connection do
     Receives the reference of a  RavenDB store and a initial store state and starts a connection, the connection
   is registered in the :connections register under the naming StoreModule.Connection
 
-  Returns: 
+  Returns:
     `{:ok, pid}` if the connecion is started
     `{:error, cause}` if the connection start failed
   """
@@ -52,7 +50,7 @@ defmodule Ravix.Connection do
     Triggers a topology update for the specified Ravix.Document.Store, this operation
     is asynchronous and will be done on background
 
-    Returns `:ok` 
+    Returns `:ok`
   """
   @spec update_topology(atom) :: :ok
   def update_topology(store) do

lib/connection/connection_state_manager.ex

@@ -1,7 +1,5 @@
 defmodule Ravix.Connection.State.Manager do
-  @moduledoc """
-    Manages the state of a RavenDB Store connection
-  """
+  @moduledoc false
   require OK
   require Logger
 

lib/connection/executor/request_executor.ex

@@ -1,11 +1,5 @@
 defmodule Ravix.Connection.RequestExecutor do
-  @moduledoc """
-  A process responsible for executing requests to the RavenDB API
-
-  Each RavenDB cluster node has it's own stateful request executor, which
-  holds how many requests this node executed, the address and infos from the Node and
-  which requests are being executed in the moment.
-  """
+  @moduledoc false
   use GenServer
   use Retry
 
@@ -86,8 +80,8 @@ defmodule Ravix.Connection.RequestExecutor do
 
     headers =
       case conn_state.disable_topology_updates do
-        false -> headers
-        true -> [{"Topology-Etag", conn_state.topology_etag}]
+        true -> headers
+        false -> [{"Topology-Etag", conn_state.topology_etag}]
       end
 
     execute_for_node(command, node_pid, nil, headers, opts)

lib/connection/executor/request_executor_option.ex

@@ -1,4 +1,5 @@
 defmodule Ravix.Connection.RequestExecutor.Options do
+  @moduledoc false
   alias Ravix.Connection.State, as: ConnectionState
 
   def from_connection_state(%ConnectionState{} = conn_state) do

lib/connection/executor/supervisor.ex

@@ -1,10 +1,5 @@
 defmodule Ravix.Connection.RequestExecutor.Supervisor do
-  @moduledoc """
-  Supervises the Requests Executors processes
-
-  Each node connection has it own supervised process, so they are completely isolated
-  from each other. All executors are registered under the :request_executors Registry.
-  """
+  @moduledoc false
   use DynamicSupervisor
 
   require Logger

lib/connection/models/node_selector.ex

@@ -1,7 +1,5 @@
 defmodule Ravix.Connection.NodeSelector do
-  @moduledoc """
-    Strategy to select nodes
-  """
+  @moduledoc false
   defstruct current_node_index: 0
 
   alias Ravix.Connection.State, as: ConnectionState

lib/connection/supervisor.ex

@@ -1,7 +1,5 @@
 defmodule Ravix.Connection.Supervisor do
-  @moduledoc """
-     Supervises and triggers the initialization of a Raven Store
-  """
+  @moduledoc false
   use Supervisor
 
   alias Ravix.Connection

lib/documents/commands/data/delete_documents.ex

@@ -1,4 +1,5 @@
 defmodule Ravix.Documents.Commands.Data.DeleteDocument do
+  @moduledoc false
   @derive {Jason.Encoder, only: [:Id, :ChangeVector, :Type]}
   defstruct Id: nil,
             ChangeVector: nil,

lib/documents/commands/data/put_documents.ex

@@ -1,4 +1,5 @@
 defmodule Ravix.Documents.Commands.Data.PutDocument do
+  @moduledoc false
   @derive {Jason.Encoder, only: [:Id, :Document, :ChangeVector, :Type]}
   defstruct Id: nil,
             Document: nil,

lib/documents/protocols/create_request.ex

@@ -1,7 +1,5 @@
 defprotocol Ravix.Documents.Protocols.CreateRequest do
-  @moduledoc """
-  Protocol to define how commands are converted to requests
-  """
+  @moduledoc false
 
   @doc """
   Creates a request based on the command

lib/documents/protocols/to_json.ex

@@ -1,4 +1,6 @@
 defprotocol Ravix.Documents.Protocols.ToJson do
+  @moduledoc false
+
   @spec to_json(t) :: any()
   @fallback_to_any true
   def to_json(command)

lib/documents/session/session.ex

@@ -1,6 +1,6 @@
 defmodule Ravix.Documents.Session do
   @moduledoc """
-  A stateful session to execute ravendb commands
+  A stateful session to execute RavenDB commands
   """
   use GenServer
 
@@ -36,6 +36,25 @@ defmodule Ravix.Documents.Session do
   ## Returns
   - `{:ok, results}`
   - `{:errors, cause}`
+
+  ## Examples
+      iex> Session.load(session_id, "entity_id")
+          {:ok,
+          %{
+            "Includes" => %{},
+            "Results" => [
+              %{
+                "@metadata" => %{
+                  "@change-vector" => "A:6450-HJrwf2z3c0G/FHJPm3zK3w",
+                  "@id" => "f13ffb17-ed7d-43b6-a483-23993db70958",
+                  "@last-modified" => "2022-04-23T11:14:16.4277047Z"
+                },
+                "cat_name" => "Coco",
+                "id" => "f13ffb17-ed7d-43b6-a483-23993db70958"
+              }
+            ],
+            "already_loaded_ids" => []
+          }}
   """
   @spec load(binary(), list() | bitstring(), any, keyword() | nil) :: any
   def load(session_id, ids, includes \\ nil, opts \\ nil)
@@ -58,13 +77,13 @@ defmodule Ravix.Documents.Session do
 
   ## Parameters
   - session_id: the session id
-  - entity: the document to be deleted
+  - entity/entity_id: the document to be deleted
 
   ## Returns
-  - `{:ok, updated_state}`
+  - `{:ok, Ravix.Documents.Session.State}`
   - `{:error, cause}`
   """
-  @spec delete(binary, map()) :: any
+  @spec delete(binary, map() | binary()) :: any
   def delete(session_id, entity) when is_map_key(entity, :id) do
     delete(session_id, entity.id)
   end
@@ -85,7 +104,7 @@ defmodule Ravix.Documents.Session do
   - change_vector: the concurrency change vector
 
   ## Returns
-  - `{:ok, updated_session}`
+  - `{:ok, Ravix.Documents.Session.State}`
   - `{:error, cause}`
   """
   @spec store(binary(), map(), binary() | nil, binary() | nil) :: any
@@ -102,6 +121,22 @@ defmodule Ravix.Documents.Session do
 
   @doc """
   Persists the session changes to the RavenDB database
+
+  Returns a [RavenDB batch response](https://ravendb.net/docs/article-page/5.3/csharp/client-api/rest-api/document-commands/batch-commands#response-format)
+
+  ## Examples
+      iex> Session.save_changes(session_id)
+          {:ok,
+          %{
+            "Results" => [
+              %{
+                "ChangeVector" => nil,
+                "Deleted" => true,
+                "Id" => "3421125e-416a-4bce-bb56-56cb4a7991ae",
+                "Type" => "DELETE"
+              }
+            ]
+          }}
   """
   @spec save_changes(binary) :: any
   def save_changes(session_id) do
@@ -112,6 +147,8 @@ defmodule Ravix.Documents.Session do
 
   @doc """
   Fetches the current session state
+
+  Returns a `{:ok, Ravix.Documents.Session.State}`
   """
   @spec fetch_state(binary()) :: {:error, :session_not_found} | {:ok, SessionState.t()}
   def fetch_state(session_id) do
@@ -132,6 +169,8 @@ defmodule Ravix.Documents.Session do
   - query: The `Ravix.RQL.Query` to be executed
   - session_id: the session_id
   - method: The http method
+
+  Returns a RavenDB query response
   """
   @spec execute_query(any, binary, any) :: any
   def execute_query(query, session_id, method) do
@@ -204,7 +243,7 @@ defmodule Ravix.Documents.Session do
 
   def handle_call({:delete, id}, _from, %SessionState{} = state) do
     case SessionManager.delete_document(state, id) do
-      {:ok, updated_state} -> {:reply, {:ok, id}, updated_state}
+      {:ok, updated_state} -> {:reply, {:ok, updated_state}, updated_state}
       {:error, err} -> {:reply, {:error, err}, state}
     end
   end

lib/documents/store.ex

@@ -58,7 +58,27 @@ defmodule Ravix.Documents.Store do
               | {:error, {:already_started, pid}}
               | {:error, term}
 
+  @doc """
+  Opens a RavenDB local session
+
+  Returns a tuple with `{:ok, uuid}` if successful or `{:error, :not_found}` if the store
+  is not initialized
+
+  ## Examples
+      iex> Ravix.Test.Store.open_session
+      {:ok, "8945c215-dd67-44da-9a64-2916e0a328d9"}
+  """
   @callback open_session() :: {:ok, binary()}
 
+  @doc """
+  Closes a RavenDB local session
+
+  Returns `:ok` if successful or `{:error, :not_found}` if the session
+  is not found
+
+  ## Examples
+      iex> Ravix.Test.Store.close_session("8945c215-dd67-44da-9a64-2916e0a328d9")
+      :ok
+  """
   @callback close_session(session_id :: binary()) :: :ok | {:error, :not_found}
 end

lib/operations/database_maintenance.ex

@@ -9,6 +9,34 @@ defmodule Ravix.Operations.Database.Maintenance do
 
   @doc """
   Creates a database using the informed request executor
+
+  Options:
+  - :encrypted = true/false
+  - :disabled = true/false
+  - :replication_factor = 1-N
+
+  ## Examples
+      iex> Ravix.Operations.Database.Maintenance.create_database(Ravix.Test.Store, "test_db")
+      {:ok,
+      %{
+        "Name" => "test_db",
+        "NodesAddedTo" => ["http://4e0373cbf5d0:8080"],
+        "RaftCommandIndex" => 443,
+        "Topology" => %{
+          "ClusterTransactionIdBase64" => "mdO7gPZsMEeslGOxxNfpjA",
+          "DatabaseTopologyIdBase64" => "0FHV8Uc0jEi94uZQiT00mA",
+          "DemotionReasons" => %{},
+          "DynamicNodesDistribution" => false,
+          "Members" => ["A"],
+          "NodesModifiedAt" => "2022-04-23T11:00:06.9470373Z",
+          "PriorityOrder" => [],
+          "Promotables" => [],
+          "PromotablesStatus" => %{},
+          "Rehabs" => [],
+          "ReplicationFactor" => 1,
+          "Stamp" => %{"Index" => 443, "LeadersTicks" => -2, "Term" => 4}
+        }
+      }}
   """
   @spec create_database(atom | pid, nil | binary, keyword) :: {:error, any} | {:ok, any}
   def create_database(store_or_pid, database_name, opts \\ [])