Add @doc for public functions

apps/block_scout_web/lib/block_scout_web/chain.ex

@@ -125,6 +125,10 @@ defmodule BlockScoutWeb.Chain do
     Map.put(next_page_params, "items_count", items_count)
   end
 
+  @doc """
+    Makes Explorer.PagingOptions map. Overloaded by different params in the input map
+    for different modules using this function.
+  """
   @spec paging_options(any) ::
           [{:paging_options, Explorer.PagingOptions.t()}, ...] | Explorer.PagingOptions.t()
   def paging_options(%{"hash" => hash_string, "fetched_coin_balance" => fetched_coin_balance_string})

apps/block_scout_web/lib/block_scout_web/controllers/api/v2/transaction_controller.ex

@@ -63,7 +63,10 @@ defmodule BlockScoutWeb.API.V2.TransactionController do
 
   @api_true [api?: true]
 
-  @spec transaction(Plug.Conn.t(), map()) :: Plug.Conn.t()
+  @doc """
+    Function to handle GET requests to `/api/v2/transactions/:transaction_hash_param` endpoint.
+  """
+  @spec transaction(Plug.Conn.t(), map()) :: Plug.Conn.t() | {atom(), any()}
   def transaction(conn, %{"transaction_hash_param" => transaction_hash_string} = params) do
     necessity_by_association =
       @transaction_necessity_by_association
@@ -90,6 +93,9 @@ defmodule BlockScoutWeb.API.V2.TransactionController do
     end
   end
 
+  @doc """
+    Function to handle GET requests to `/api/v2/transactions` endpoint.
+  """
   @spec transactions(Plug.Conn.t(), map()) :: Plug.Conn.t()
   def transactions(conn, params) do
     filter_options = filter_options(params, :validated)
@@ -114,6 +120,10 @@ defmodule BlockScoutWeb.API.V2.TransactionController do
     |> render(:transactions, %{transactions: transactions, next_page_params: next_page_params})
   end
 
+  @doc """
+    Function to handle GET requests to `/api/v2/transactions/zkevm-batch/:batch_number` endpoint.
+    It renders the list of L2 transactions bound to the specified batch.
+  """
   @spec zkevm_batch(Plug.Conn.t(), map()) :: Plug.Conn.t()
   def zkevm_batch(conn, %{"batch_number" => batch_number} = _params) do
     transactions =
@@ -127,7 +137,10 @@ defmodule BlockScoutWeb.API.V2.TransactionController do
     |> render(:transactions, %{transactions: transactions})
   end
 
-  @spec raw_trace(Plug.Conn.t(), map()) :: Plug.Conn.t()
+  @doc """
+    Function to handle GET requests to `/api/v2/transactions/:transaction_hash_param/raw-trace` endpoint.
+  """
+  @spec raw_trace(Plug.Conn.t(), map()) :: Plug.Conn.t() | {atom(), any()}
   def raw_trace(conn, %{"transaction_hash_param" => transaction_hash_string} = params) do
     with {:format, {:ok, transaction_hash}} <- {:format, Chain.string_to_transaction_hash(transaction_hash_string)},
          {:not_found, {:ok, transaction}} <-
@@ -157,6 +170,9 @@ defmodule BlockScoutWeb.API.V2.TransactionController do
     end
   end
 
+  @doc """
+    Function to handle GET requests to `/api/v2/transactions/:transaction_hash_param/token-transfers` endpoint.
+  """
   @spec token_transfers(Plug.Conn.t(), map()) :: Plug.Conn.t() | {atom(), any()}
   def token_transfers(conn, %{"transaction_hash_param" => transaction_hash_string} = params) do
     with {:format, {:ok, transaction_hash}} <- {:format, Chain.string_to_transaction_hash(transaction_hash_string)},
@@ -190,6 +206,9 @@ defmodule BlockScoutWeb.API.V2.TransactionController do
     end
   end
 
+  @doc """
+    Function to handle GET requests to `/api/v2/transactions/:transaction_hash_param/internal-transactions` endpoint.
+  """
   @spec internal_transactions(Plug.Conn.t(), map()) :: Plug.Conn.t() | {atom(), any()}
   def internal_transactions(conn, %{"transaction_hash_param" => transaction_hash_string} = params) do
     with {:format, {:ok, transaction_hash}} <- {:format, Chain.string_to_transaction_hash(transaction_hash_string)},
@@ -219,6 +238,9 @@ defmodule BlockScoutWeb.API.V2.TransactionController do
     end
   end
 
+  @doc """
+    Function to handle GET requests to `/api/v2/transactions/:transaction_hash_param/logs` endpoint.
+  """
   @spec logs(Plug.Conn.t(), map()) :: Plug.Conn.t() | {atom(), any()}
   def logs(conn, %{"transaction_hash_param" => transaction_hash_string} = params) do
     with {:format, {:ok, transaction_hash}} <- {:format, Chain.string_to_transaction_hash(transaction_hash_string)},
@@ -255,6 +277,9 @@ defmodule BlockScoutWeb.API.V2.TransactionController do
     end
   end
 
+  @doc """
+    Function to handle GET requests to `/api/v2/transactions/:transaction_hash_param/state-changes` endpoint.
+  """
   @spec state_changes(Plug.Conn.t(), map()) :: Plug.Conn.t() | {atom(), any()}
   def state_changes(conn, %{"transaction_hash_param" => transaction_hash_string} = params) do
     with {:format, {:ok, transaction_hash}} <- {:format, Chain.string_to_transaction_hash(transaction_hash_string)},
@@ -282,7 +307,10 @@ defmodule BlockScoutWeb.API.V2.TransactionController do
     end
   end
 
-  @spec watchlist_transactions(Plug.Conn.t(), map()) :: Plug.Conn.t() | {atom(), any()}
+  @doc """
+    Function to handle GET requests to `/api/v2/transactions/watchlist` endpoint.
+  """
+  @spec watchlist_transactions(Plug.Conn.t(), map()) :: Plug.Conn.t() | {:auth, any()}
   def watchlist_transactions(conn, params) do
     with {:auth, %{watchlist_id: watchlist_id}} <- {:auth, current_user(conn)} do
       full_options =

apps/block_scout_web/lib/block_scout_web/controllers/api/v2/zkevm_controller.ex

@@ -23,6 +23,9 @@ defmodule BlockScoutWeb.API.V2.ZkevmController do
     :verify_transaction => :optional
   }
 
+  @doc """
+    Function to handle GET requests to `/api/v2/zkevm/batches/:batch_number` endpoint.
+  """
   @spec batch(Plug.Conn.t(), map()) :: Plug.Conn.t()
   def batch(conn, %{"batch_number" => batch_number} = _params) do
     {:ok, batch} =
@@ -37,6 +40,9 @@ defmodule BlockScoutWeb.API.V2.ZkevmController do
     |> render(:zkevm_batch, %{batch: batch})
   end
 
+  @doc """
+    Function to handle GET requests to `/api/v2/main-page/zkevm/batches/latest-number` endpoint.
+  """
   @spec batch_latest_number(Plug.Conn.t(), map()) :: Plug.Conn.t()
   def batch_latest_number(conn, _params) do
     conn
@@ -44,6 +50,9 @@ defmodule BlockScoutWeb.API.V2.ZkevmController do
     |> render(:zkevm_batch_latest_number, %{number: batch_latest_number()})
   end
 
+  @doc """
+    Function to handle GET requests to `/api/v2/zkevm/batches` endpoint.
+  """
   @spec batches(Plug.Conn.t(), map()) :: Plug.Conn.t()
   def batches(conn, params) do
     {batches, next_page} =
@@ -64,6 +73,9 @@ defmodule BlockScoutWeb.API.V2.ZkevmController do
     })
   end
 
+  @doc """
+    Function to handle GET requests to `/api/v2/zkevm/batches/count` endpoint.
+  """
   @spec batches_count(Plug.Conn.t(), map()) :: Plug.Conn.t()
   def batches_count(conn, _params) do
     conn
@@ -71,6 +83,9 @@ defmodule BlockScoutWeb.API.V2.ZkevmController do
     |> render(:zkevm_batches_count, %{count: batch_latest_number()})
   end
 
+  @doc """
+    Function to handle GET requests to `/api/v2/main-page/zkevm/batches/confirmed` endpoint.
+  """
   @spec batches_confirmed(Plug.Conn.t(), map()) :: Plug.Conn.t()
   def batches_confirmed(conn, _params) do
     batches =

apps/block_scout_web/lib/block_scout_web/views/api/v2/zkevm_view.ex

@@ -1,6 +1,9 @@
 defmodule BlockScoutWeb.API.V2.ZkevmView do
   use BlockScoutWeb, :view
 
+  @doc """
+    Function to render GET requests to `/api/v2/zkevm/batches/:batch_number` endpoint.
+  """
   @spec render(binary(), map()) :: map() | non_neg_integer()
   def render("zkevm_batch.json", %{batch: batch}) do
     sequence_tx_hash =
@@ -26,6 +29,9 @@ defmodule BlockScoutWeb.API.V2.ZkevmView do
     }
   end
 
+  @doc """
+    Function to render GET requests to `/api/v2/zkevm/batches` endpoint.
+  """
   def render("zkevm_batches.json", %{
         batches: batches,
         next_page_params: next_page_params
@@ -36,14 +42,23 @@ defmodule BlockScoutWeb.API.V2.ZkevmView do
     }
   end
 
+  @doc """
+    Function to render GET requests to `/api/v2/main-page/zkevm/batches/confirmed` endpoint.
+  """
   def render("zkevm_batches.json", %{batches: batches}) do
     %{items: render_zkevm_batches(batches)}
   end
 
+  @doc """
+    Function to render GET requests to `/api/v2/zkevm/batches/count` endpoint.
+  """
   def render("zkevm_batches_count.json", %{count: count}) do
     count
   end
 
+  @doc """
+    Function to render GET requests to `/api/v2/main-page/zkevm/batches/latest-number` endpoint.
+  """
   def render("zkevm_batch_latest_number.json", %{number: number}) do
     number
   end

apps/explorer/lib/explorer/chain/zkevm/batch_transaction.ex

@@ -23,6 +23,9 @@ defmodule Explorer.Chain.Zkevm.BatchTransaction do
     timestamps()
   end
 
+  @doc """
+    Validates that the `attrs` are valid.
+  """
   @spec changeset(Ecto.Schema.t(), map()) :: Ecto.Schema.t()
   def changeset(%__MODULE__{} = transactions, attrs \\ %{}) do
     transactions

apps/explorer/lib/explorer/chain/zkevm/lifecycle_transaction.ex

@@ -24,6 +24,9 @@ defmodule Explorer.Chain.Zkevm.LifecycleTransaction do
     timestamps()
   end
 
+  @doc """
+    Validates that the `attrs` are valid.
+  """
   @spec changeset(Ecto.Schema.t(), map()) :: Ecto.Schema.t()
   def changeset(%__MODULE__{} = txn, attrs \\ %{}) do
     txn

apps/explorer/lib/explorer/chain/zkevm/reader.ex

@@ -15,6 +15,11 @@ defmodule Explorer.Chain.Zkevm.Reader do
   alias Explorer.Chain.Zkevm.{BatchTransaction, LifecycleTransaction, TransactionBatch}
   alias Explorer.{Chain, PagingOptions, Repo}
 
+  @doc """
+    Reads a batch by its number from database.
+    If the number is :latest, gets the latest batch from `zkevm_transaction_batches` table.
+    Returns {:error, :not_found} in case the batch is not found.
+  """
   @spec batch(non_neg_integer() | :latest, list()) :: {:ok, map()} | {:error, :not_found}
   def batch(number, options \\ [])
 
@@ -42,6 +47,10 @@ defmodule Explorer.Chain.Zkevm.Reader do
     end
   end
 
+  @doc """
+    Reads a list of batches from `zkevm_transaction_batches` table.
+  """
+  @spec batches(list()) :: list()
   def batches(options \\ []) do
     necessity_by_association = Keyword.get(options, :necessity_by_association, %{})
 
@@ -68,12 +77,21 @@ defmodule Explorer.Chain.Zkevm.Reader do
     select_repo(options).all(query)
   end
 
+  @doc """
+    Reads a list of L2 transaction hashes from `zkevm_batch_l2_transactions` table.
+  """
+  @spec batch_transactions(non_neg_integer(), list()) :: list()
   def batch_transactions(batch_number, options \\ []) do
     query = from(bts in BatchTransaction, where: bts.batch_number == ^batch_number)
 
     select_repo(options).all(query)
   end
 
+  @doc """
+    Gets the number of the latest batch with defined verify_id from `zkevm_transaction_batches` table.
+    Returns 0 if not found.
+  """
+  @spec last_verified_batch_number() :: non_neg_integer()
   def last_verified_batch_number do
     query =
       from(tb in TransactionBatch,
@@ -88,6 +106,10 @@ defmodule Explorer.Chain.Zkevm.Reader do
     |> Kernel.||(0)
   end
 
+  @doc """
+    Reads a list of L1 transactions by their hashes from `zkevm_lifecycle_l1_transactions` table.
+  """
+  @spec lifecycle_transactions(list()) :: list()
   def lifecycle_transactions(l1_tx_hashes) do
     query =
       from(
@@ -99,6 +121,10 @@ defmodule Explorer.Chain.Zkevm.Reader do
     Repo.all(query, timeout: :infinity)
   end
 
+  @doc """
+    Determines ID of the future lifecycle transaction by reading `zkevm_lifecycle_l1_transactions` table.
+  """
+  @spec next_id() :: non_neg_integer()
   def next_id do
     query =
       from(lt in LifecycleTransaction,

apps/explorer/lib/explorer/chain/zkevm/transaction_batch.ex

@@ -45,6 +45,9 @@ defmodule Explorer.Chain.Zkevm.TransactionBatch do
     timestamps()
   end
 
+  @doc """
+    Validates that the `attrs` are valid.
+  """
   @spec changeset(Ecto.Schema.t(), map()) :: Ecto.Schema.t()
   def changeset(%__MODULE__{} = batches, attrs \\ %{}) do
     batches