From aa6f7194d6ec941b1885e6800798985820b64d1a Mon Sep 17 00:00:00 2001
From: Shahryar Tavakkoli <shahryar.tbiz@gmail.com>
Date: Wed, 6 Mar 2024 15:30:03 +0330
Subject: [PATCH] add entry docs of mnesia information, based on #28

---
 .../mnesia_assistant/mnesia_assistant.ex      | 25 +++++
 .../mnesia_assistant/operation/information.ex | 92 +++++++++++++++++--
 2 files changed, 111 insertions(+), 6 deletions(-)

diff --git a/lib/modules/mnesia_assistant/mnesia_assistant.ex b/lib/modules/mnesia_assistant/mnesia_assistant.ex
index 8e2024f..ec8f0ad 100644
--- a/lib/modules/mnesia_assistant/mnesia_assistant.ex
+++ b/lib/modules/mnesia_assistant/mnesia_assistant.ex
@@ -171,6 +171,25 @@ defmodule MnesiaAssistant do
 
   def unsubscribe(what), do: Mnesia.unsubscribe(what)
 
+  @doc """
+  When tracing a system of Mnesia applications it is useful to be able to
+  interleave Mnesia own events with `application-related` events that give
+  information about the application context.
+
+  Whenever the application begins a new and demanding Mnesia task,
+  or if it enters a new interesting phase in its execution, it can be a good idea
+  to use mnesia:report_event/1. Event can be any term and generates
+  a `{mnesia_user, Event}` event for any processes that subscribe
+  to Mnesia system events. for more information read `subscribe/1` document.
+
+  ### Example:
+
+  ```elixir
+  MnesiaAssistant.report_event(event)
+  ```
+  """
+  def report_event(event), do: Mnesia.report_event(event)
+
   @doc """
   The `:mnesia.change_config/2` function in Mnesia, the distributed database management
   system in Erlang/OTP, is used to dynamically change the configuration parameters
@@ -182,6 +201,12 @@ defmodule MnesiaAssistant do
 
   * `config`: --> extra_db_nodes | dc_dump_limit
   * `value`: -->  [node()] | number()
+
+  ### Example
+
+  ```elixir
+  MnesiaAssistant.change_config(config, value)
+  ```
   """
   def change_config(config, value) when config in [:extra_db_nodes, :dc_dump_limit],
     do: Mnesia.change_config(config, value)
diff --git a/lib/modules/mnesia_assistant/operation/information.ex b/lib/modules/mnesia_assistant/operation/information.ex
index 5e0c74a..15fd0d3 100644
--- a/lib/modules/mnesia_assistant/operation/information.ex
+++ b/lib/modules/mnesia_assistant/operation/information.ex
@@ -1,6 +1,7 @@
 defmodule MnesiaAssistant.Information do
   @moduledoc """
-
+  This particular module is actually a set of functions in `Mnesia` that are designed
+  to supply the user with the information that they require regarding the system.
   """
   alias :mnesia, as: Mnesia
   @debug_level_types [:none, :verbose, :debug, :trace, false, true]
@@ -42,10 +43,64 @@ defmodule MnesiaAssistant.Information do
   ]
 
   @doc """
+  This function is actually a combination of two functions
+  in mnesia(`:mnesia.info()`, `:mnesia.schema()`).
+
+  ### Example:
 
+  ```elixir
+    MnesiaAssistant.Information.info()
+    # OR
+    MnesiaAssistant.Information.info({:system, type})
+    # OR
+    MnesiaAssistant.Information.info(type)
+  ```
+
+  All types you can use:
+  ```
+    [
+      :all,
+      :access_module,
+      :auto_repair,
+      :backup_module,
+      :checkpoints,
+      :event_module,
+      :db_nodes,
+      :debug,
+      :directory,
+      :dump_log_load_regulation,
+      :dump_log_time_threshold,
+      :dump_log_update_in_place,
+      :dump_log_write_threshold,
+      :extra_db_nodes,
+      :fallback_activated,
+      :held_locks,
+      :is_running,
+      :local_tables,
+      :lock_queue,
+      :log_version,
+      :master_node_tables,
+      :protocol_version,
+      :running_db_nodes,
+      :schema_location,
+      :subscribers,
+      :tables,
+      :transactions,
+      :transaction_failures,
+      :transaction_commits,
+      :transaction_restarts,
+      :transaction_log_writes,
+      :use_dir,
+      :version,
+      :schema
+    ]
+  ```
   """
   def info(), do: Mnesia.info()
 
+  @doc """
+  Read `info/0` document.
+  """
   def info({:system, type}) when type in @system_types, do: Mnesia.system_info(type)
 
   def info(type) when type in @system_types, do: Mnesia.system_info(type)
@@ -53,23 +108,48 @@ defmodule MnesiaAssistant.Information do
   def info(:schema), do: Mnesia.schema()
 
   @doc """
-
+  Read `info/0` document.
   """
   def system_info(type) when is_atom(type), do: Mnesia.system_info(type)
 
   @doc """
+  If the application detects a communication failure (in a potentially partitioned network)
+  that can have caused an inconsistent database, it can use the function
+  `mnesia:set_master_nodes(Tab, MasterNodes)` to define from which nodes
+  each table is to be loaded. At startup, the Mnesia normal table load algorithm is
+  bypassed and the table is loaded from one of the master nodes defined for the table,
+  regardless of when and if Mnesia terminated on other nodes. MasterNodes can only
+  contain nodes where the table has a replica. If the MasterNodes list is empty,
+  the master node recovery mechanism for the particular table is reset,
+  and the normal load mechanism is used at the next restart.
+
+  > The master node setting is always local. It can be changed regardless
+  > if Mnesia is started or not.
 
+  The database can also become inconsistent if configuration
+  parameter `max_wait_for_decision` is used or if `mnesia:force_load_table/1` is used.
+
+  ### Example:
+
+  ```elixir
+    MnesiaAssistant.Information.set_debug_level(level)
+  ```
+
+  All level you can use: `[:none, :verbose, :debug, :trace, false, true]`
   """
   def set_debug_level(level) when level in @debug_level_types,
     do: Mnesia.set_debug_level(level)
 
   @doc """
+  Ensures that the local transaction log file is synced to disk.
+  On a single node system, data written to disk tables since the
+  last dump can be lost if there is a power outage.
 
-  """
-  def report_event(event), do: Mnesia.report_event(event)
-
-  @doc """
+  ### Example:
 
+  ```elixir
+  MnesiaAssistant.Information.sync_log()
+  ```
   """
   def sync_log(), do: Mnesia.sync_log()
 end