docs: Enhance Phoenix.SessionProcess module documentation

Significantly improved the main module documentation with comprehensive
@moduledoc and @doc comments for all public functions.

## Changes

### Module Documentation (@moduledoc)
- Complete rewrite with detailed feature overview
- Quick start guide with code examples
- Configuration instructions
- Custom session process examples
- API overview grouped by category
- Error handling documentation
- Performance metrics

### Function Documentation
- Added comprehensive @doc for all delegated functions:
  - start/1, start/2, start/3 - with parameters, returns, examples
  - started?/1 - with clear boolean return documentation
  - terminate/1 - with graceful shutdown details
  - call/2, call/3 - with timeout and error handling
  - cast/2 - with async messaging details

- Enhanced existing @doc comments:
  - list_session/0 - comprehensive examples
  - session_info/0 - return value documentation
  - find_session/1 - comparison with started?/1
  - session_stats/0 - detailed stats breakdown
  - list_sessions_by_module/1 - filter documentation

### Documentation Improvements
- Clear parameter descriptions
- Comprehensive return value documentation
- Multiple usage examples for each function
- Error case handling examples
- Performance expectations
- Integration patterns

## Impact
+261 lines of documentation
All public API functions now have detailed @doc comments
Improved developer experience and API discoverability

Co-Authored-By: Claude <[email protected]>

Author: GSMLG-BOT

lib/phoenix/session_process.ex

@@ -1,62 +1,196 @@
 defmodule Phoenix.SessionProcess do
   @moduledoc """
-  Documentation for `Phoenix.SessionProcess`.
+  Main API for managing isolated session processes in Phoenix applications.
 
-  Add superviser to process tree
+  This module provides a high-level interface for creating, managing, and communicating
+  with dedicated GenServer processes for each user session. Each session runs in its own
+  isolated process, enabling real-time session state management without external dependencies.
 
-      [
-        ...
-        {Phoenix.SessionProcess.Supervisor, []}
-      ]
+  ## Features
 
-  Add this after the `:fetch_session` plug to generate a unique session ID.
+  - **Session Isolation**: Each user session runs in a dedicated GenServer process
+  - **Automatic Cleanup**: TTL-based session expiration and garbage collection
+  - **LiveView Integration**: Built-in support for monitoring LiveView processes
+  - **High Performance**: 10,000+ sessions/second creation rate
+  - **Zero Dependencies**: No Redis, databases, or external services required
+  - **Comprehensive Telemetry**: Built-in observability for all operations
 
-      plug :fetch_session
-      plug Phoenix.SessionProcess.SessionId
+  ## Quick Start
 
-  Start a session process with a session ID.
+  ### 1. Add to Supervision Tree
 
-      Phoenix.SessionProcess.start("session_id")
+  Add the supervisor to your application's supervision tree in `lib/my_app/application.ex`:
 
-  This will start a session process using the module defined with
+      def start(_type, _args) do
+        children = [
+          # ... other children ...
+          {Phoenix.SessionProcess.Supervisor, []}
+        ]
 
-      config :phoenix_session_process, session_process: MySessionProcess
+        Supervisor.start_link(children, strategy: :one_for_one)
+      end
+
+  ### 2. Configure Session ID Generation
+
+  Add the SessionId plug after `:fetch_session` in your router:
+
+      pipeline :browser do
+        plug :accepts, ["html"]
+        plug :fetch_session
+        plug Phoenix.SessionProcess.SessionId  # Add this
+        # ... other plugs ...
+      end
+
+  ### 3. Use in Controllers and LiveViews
+
+      defmodule MyAppWeb.PageController do
+        use MyAppWeb, :controller
+
+        def index(conn, _params) do
+          session_id = conn.assigns.session_id
+
+          # Start session process
+          {:ok, _pid} = Phoenix.SessionProcess.start(session_id)
+
+          # Store data
+          Phoenix.SessionProcess.cast(session_id, {:put, :user_id, 123})
+
+          # Retrieve data
+          {:ok, state} = Phoenix.SessionProcess.call(session_id, :get_state)
+
+          render(conn, "index.html", state: state)
+        end
+      end
+
+  ## Configuration
+
+  Configure the library in `config/config.exs`:
+
+      config :phoenix_session_process,
+        session_process: MyApp.SessionProcess,  # Default session module
+        max_sessions: 10_000,                   # Maximum concurrent sessions
+        session_ttl: 3_600_000,                # Session TTL (1 hour)
+        rate_limit: 100                        # Sessions per minute
+
+  ## Creating Custom Session Processes
 
-  Or you can start a session process with a specific module.
+  ### Basic Session Process
 
-      Phoenix.SessionProcess.start("session_id", MySessionProcess)
-      # or
-      Phoenix.SessionProcess.start("session_id", MySessionProcess, arg)
+      defmodule MyApp.SessionProcess do
+        use Phoenix.SessionProcess, :process
 
-  Check if a session process is started.
+        @impl true
+        def init(_init_arg) do
+          {:ok, %{user_id: nil, cart: [], preferences: %{}}}
+        end
 
-      Phoenix.SessionProcess.started?("session_id")
+        @impl true
+        def handle_call(:get_user, _from, state) do
+          {:reply, state.user_id, state}
+        end
 
-  Terminate a session process.
+        @impl true
+        def handle_cast({:set_user, user_id}, state) do
+          {:noreply, %{state | user_id: user_id}}
+        end
+      end
 
-      Phoenix.SessionProcess.terminate("session_id")
+  ### With LiveView Integration
 
-  Genserver call on a session process.
+      defmodule MyApp.SessionProcessWithLiveView do
+        use Phoenix.SessionProcess, :process_link
 
-      Phoenix.SessionProcess.call("session_id", request)
+        @impl true
+        def init(_init_arg) do
+          {:ok, %{user: nil, live_views: []}}
+        end
 
-  Genserver cast on a session process.
+        # Automatically monitors LiveView processes
+        # Sends :session_expired message when session terminates
+      end
 
-      Phoenix.SessionProcess.cast("session_id", request)
+  ## API Overview
 
-  List all session processes.
+  ### Session Management
+  - `start/1`, `start/2`, `start/3` - Start session processes
+  - `started?/1` - Check if session exists
+  - `terminate/1` - Stop session process
+  - `find_session/1` - Find session by ID
 
-      Phoenix.SessionProcess.list_session()
+  ### Communication
+  - `call/2`, `call/3` - Synchronous requests
+  - `cast/2` - Asynchronous messages
+
+  ### Inspection
+  - `list_session/0` - List all sessions
+  - `session_info/0` - Get session count and modules
+  - `session_stats/0` - Get memory and performance stats
+  - `list_sessions_by_module/1` - Filter sessions by module
+
+  ## Error Handling
+
+  All operations return structured error tuples:
+
+      {:error, {:invalid_session_id, session_id}}
+      {:error, {:session_limit_reached, max_sessions}}
+      {:error, {:session_not_found, session_id}}
+      {:error, {:timeout, timeout}}
+
+  Use `Phoenix.SessionProcess.Error.message/1` for human-readable errors.
+
+  ## Performance
+
+  Expected performance metrics:
+  - Session Creation: 10,000+ sessions/sec
+  - Memory Usage: ~10KB per session
+  - Registry Lookups: 100,000+ lookups/sec
+
+  See the benchmarking guide at `bench/README.md` for details.
   """
 
+  @doc """
+  Starts a session process using the default configured module.
+
+  The session process is registered in the Registry and scheduled for automatic
+  cleanup based on the configured TTL.
+
+  ## Parameters
+  - `session_id` - Unique binary identifier for the session
+
+  ## Returns
+  - `{:ok, pid}` - Session process started successfully
+  - `{:error, {:already_started, pid}}` - Session already exists
+  - `{:error, {:invalid_session_id, id}}` - Invalid session ID format
+  - `{:error, {:session_limit_reached, max}}` - Maximum sessions exceeded
+
+  ## Examples
+
+      {:ok, pid} = Phoenix.SessionProcess.start("user_123")
+      {:error, {:already_started, pid}} = Phoenix.SessionProcess.start("user_123")
+  """
   @spec start(binary()) :: {:ok, pid()} | {:error, term()}
   defdelegate start(session_id), to: Phoenix.SessionProcess.ProcessSupervisor, as: :start_session
 
   @doc """
-  Start a session process with a specific module.
+  Starts a session process using a custom module.
+
+  This allows you to use a specific session process implementation instead of
+  the default configured module.
+
+  ## Parameters
+  - `session_id` - Unique binary identifier for the session
+  - `module` - Module implementing the session process behavior
+
+  ## Returns
+  - `{:ok, pid}` - Session process started successfully
+  - `{:error, {:already_started, pid}}` - Session already exists
+  - `{:error, {:invalid_session_id, id}}` - Invalid session ID format
+  - `{:error, {:session_limit_reached, max}}` - Maximum sessions exceeded
 
   ## Examples
 
+      {:ok, pid} = Phoenix.SessionProcess.start("user_123", MyApp.CustomSessionProcess)
+
       iex> result = Phoenix.SessionProcess.start("valid_session", Phoenix.SessionProcess.DefaultSessionProcess)
       iex> match?({:ok, _pid}, result) or match?({:error, {:already_started, _pid}}, result)
       true
@@ -70,10 +204,30 @@ defmodule Phoenix.SessionProcess do
     as: :start_session
 
   @doc """
-  Start a session process with a specific module and initialization arguments.
+  Starts a session process with a custom module and initialization arguments.
+
+  The initialization arguments are passed to the module's `init/1` callback,
+  allowing you to set up initial state or configuration.
+
+  ## Parameters
+  - `session_id` - Unique binary identifier for the session
+  - `module` - Module implementing the session process behavior
+  - `arg` - Initialization argument(s) passed to `init/1`
+
+  ## Returns
+  - `{:ok, pid}` - Session process started successfully
+  - `{:error, {:already_started, pid}}` - Session already exists
+  - `{:error, {:invalid_session_id, id}}` - Invalid session ID format
+  - `{:error, {:session_limit_reached, max}}` - Maximum sessions exceeded
 
   ## Examples
 
+      # With map argument
+      {:ok, pid} = Phoenix.SessionProcess.start("user_123", MyApp.SessionProcess, %{user_id: 123})
+
+      # With keyword list
+      {:ok, pid} = Phoenix.SessionProcess.start("user_456", MyApp.SessionProcess, [debug: true])
+
       iex> result = Phoenix.SessionProcess.start("valid_session_with_args", Phoenix.SessionProcess.DefaultSessionProcess, %{user_id: 123})
       iex> match?({:ok, _pid}, result) or match?({:error, {:already_started, _pid}}, result)
       true
@@ -87,21 +241,98 @@ defmodule Phoenix.SessionProcess do
     to: Phoenix.SessionProcess.ProcessSupervisor,
     as: :start_session
 
+  @doc """
+  Checks if a session process is currently running.
+
+  ## Parameters
+  - `session_id` - Unique binary identifier for the session
+
+  ## Returns
+  - `true` - Session process exists and is running
+  - `false` - Session process does not exist
+
+  ## Examples
+
+      {:ok, _pid} = Phoenix.SessionProcess.start("user_123")
+      true = Phoenix.SessionProcess.started?("user_123")
+      false = Phoenix.SessionProcess.started?("nonexistent")
+  """
   @spec started?(binary()) :: boolean()
   defdelegate started?(session_id),
     to: Phoenix.SessionProcess.ProcessSupervisor,
     as: :session_process_started?
 
+  @doc """
+  Terminates a session process.
+
+  This gracefully shuts down the session process and removes it from the Registry.
+  Emits telemetry events for session stop.
+
+  ## Parameters
+  - `session_id` - Unique binary identifier for the session
+
+  ## Returns
+  - `:ok` - Session terminated successfully
+  - `{:error, :not_found}` - Session does not exist
+
+  ## Examples
+
+      {:ok, _pid} = Phoenix.SessionProcess.start("user_123")
+      :ok = Phoenix.SessionProcess.terminate("user_123")
+      {:error, :not_found} = Phoenix.SessionProcess.terminate("user_123")
+  """
   @spec terminate(binary()) :: :ok | {:error, :not_found}
   defdelegate terminate(session_id),
     to: Phoenix.SessionProcess.ProcessSupervisor,
     as: :terminate_session
 
-  @spec call(binary(), any(), :infinity | non_neg_integer()) :: {:ok, any()} | {:error, term()}
+  @doc """
+  Makes a synchronous call to a session process.
+
+  Sends a synchronous request to the session process and waits for a response.
+  The request is handled by the session process's `handle_call/3` callback.
+
+  ## Parameters
+  - `session_id` - Unique binary identifier for the session
+  - `request` - The request message to send
+  - `timeout` - Maximum time to wait for response in milliseconds (default: 15,000)
+
+  ## Returns
+  - Response from the session process's `handle_call/3` callback
+  - `{:error, {:session_not_found, id}}` - Session does not exist
+  - `{:error, {:timeout, timeout}}` - Request timed out
+
+  ## Examples
+
+      {:ok, _pid} = Phoenix.SessionProcess.start("user_123")
+      {:ok, state} = Phoenix.SessionProcess.call("user_123", :get_state)
+      {:ok, :pong} = Phoenix.SessionProcess.call("user_123", :ping, 5_000)
+  """
+  @spec call(binary(), any(), :infinity | non_neg_integer()) :: any()
   defdelegate call(session_id, request, timeout \\ 15_000),
     to: Phoenix.SessionProcess.ProcessSupervisor,
     as: :call_on_session
 
+  @doc """
+  Sends an asynchronous message to a session process.
+
+  Sends a fire-and-forget message to the session process. The message is handled
+  by the session process's `handle_cast/2` callback. Does not wait for a response.
+
+  ## Parameters
+  - `session_id` - Unique binary identifier for the session
+  - `request` - The message to send
+
+  ## Returns
+  - `:ok` - Message sent successfully
+  - `{:error, {:session_not_found, id}}` - Session does not exist
+
+  ## Examples
+
+      {:ok, _pid} = Phoenix.SessionProcess.start("user_123")
+      :ok = Phoenix.SessionProcess.cast("user_123", {:put, :user_id, 123})
+      :ok = Phoenix.SessionProcess.cast("user_123", {:delete, :old_key})
+  """
   @spec cast(binary(), any()) :: :ok | {:error, term()}
   defdelegate cast(session_id, request),
     to: Phoenix.SessionProcess.ProcessSupervisor,