From 6922086fa12485d75298962c78a51c0cfc800a15 Mon Sep 17 00:00:00 2001
From: Moritz <moritz.m@local-it.org>
Date: Mon, 10 Nov 2025 16:26:35 +0100
Subject: [PATCH] docs: add @doc to public functions in MemberLive.Index

Document LiveView callbacks (mount, handle_event, handle_info, handle_params)
with comprehensive descriptions of their purpose and supported operations.
---
 lib/mv_web/live/member_live/index.ex | 33 +++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/lib/mv_web/live/member_live/index.ex b/lib/mv_web/live/member_live/index.ex
index f3ceb74..7b20278 100644
--- a/lib/mv_web/live/member_live/index.ex
+++ b/lib/mv_web/live/member_live/index.ex
@@ -26,6 +26,12 @@ defmodule MvWeb.MemberLive.Index do
   """
   use MvWeb, :live_view
 
+  @doc """
+  Initializes the LiveView state.
+
+  Sets up initial assigns for page title, search query, sort configuration,
+  and member selection. Actual data loading happens in `handle_params/3`.
+  """
   @impl true
   def mount(_params, _session, socket) do
     socket =
@@ -44,7 +50,14 @@ defmodule MvWeb.MemberLive.Index do
   # Handle Events
   # -----------------------------------------------------------------
 
-  # Delete a member
+  @doc """
+  Handles member-related UI events.
+
+  ## Supported events:
+  - `"delete"` - Removes a member from the database
+  - `"select_member"` - Toggles individual member selection
+  - `"select_all"` - Toggles selection of all visible members
+  """
   @impl true
   def handle_event("delete", %{"id" => id}, socket) do
     member = Ash.get!(Mv.Membership.Member, id)
@@ -54,7 +67,6 @@ defmodule MvWeb.MemberLive.Index do
     {:noreply, assign(socket, :members, updated_members)}
   end
 
-  # Selects one member in the list of members
   @impl true
   def handle_event("select_member", %{"id" => id}, socket) do
     selected =
@@ -67,7 +79,6 @@ defmodule MvWeb.MemberLive.Index do
     {:noreply, assign(socket, :selected_members, selected)}
   end
 
-  #  Selects all members in the list of members
   @impl true
   def handle_event("select_all", _params, socket) do
     members = socket.assigns.members
@@ -88,7 +99,13 @@ defmodule MvWeb.MemberLive.Index do
   # Handle Infos from Child Components
   # -----------------------------------------------------------------
 
-  # Sorts the list of members according to a field, when you click on the column header
+  @doc """
+  Handles messages from child components.
+
+  ## Supported messages:
+  - `{:sort, field}` - Sort event from SortHeaderComponent. Updates sort field/order and syncs URL
+  - `{:search_changed, query}` - Search event from SearchBarComponent. Filters members and syncs URL
+  """
   @impl true
   def handle_info({:sort, field_str}, socket) do
     field = String.to_existing_atom(field_str)
@@ -138,7 +155,6 @@ defmodule MvWeb.MemberLive.Index do
      )}
   end
 
-  # Function to handle search
   @impl true
   def handle_info({:search_changed, q}, socket) do
     socket = load_members(socket, q)
@@ -167,6 +183,13 @@ defmodule MvWeb.MemberLive.Index do
   # -----------------------------------------------------------------
   # Handle Params from the URL
   # -----------------------------------------------------------------
+  @doc """
+  Handles URL parameter changes.
+
+  Parses query parameters for search query, sort field, and sort order,
+  then loads members accordingly. This enables bookmarkable URLs and
+  browser back/forward navigation.
+  """
   @impl true
   def handle_params(params, _url, socket) do
     socket =