From ca846336419ada02ae1377efede91c9120846c19 Mon Sep 17 00:00:00 2001
From: Moritz <moritz.m@local-it.org>
Date: Mon, 10 Nov 2025 16:24:56 +0100
Subject: [PATCH] docs: add @moduledoc to all LiveView modules

Add comprehensive module documentation to 12 LiveView modules covering
member, user, property, and property_type management views.
---
 lib/mv_web/live/member_live/form.ex         | 29 ++++++++++++++++++
 lib/mv_web/live/member_live/index.ex        | 25 +++++++++++++++
 lib/mv_web/live/member_live/show.ex         | 22 +++++++++++++
 lib/mv_web/live/property_live/form.ex       | 31 +++++++++++++++++++
 lib/mv_web/live/property_live/index.ex      | 22 +++++++++++++
 lib/mv_web/live/property_live/show.ex       | 20 ++++++++++++
 lib/mv_web/live/property_type_live/form.ex  | 34 +++++++++++++++++++++
 lib/mv_web/live/property_type_live/index.ex | 24 +++++++++++++++
 lib/mv_web/live/property_type_live/show.ex  | 23 ++++++++++++++
 lib/mv_web/live/user_live/form.ex           | 32 +++++++++++++++++++
 lib/mv_web/live/user_live/index.ex          | 21 +++++++++++++
 lib/mv_web/live/user_live/show.ex           | 25 +++++++++++++++
 12 files changed, 308 insertions(+)

diff --git a/lib/mv_web/live/member_live/form.ex b/lib/mv_web/live/member_live/form.ex
index 521d501..ba7ba36 100644
--- a/lib/mv_web/live/member_live/form.ex
+++ b/lib/mv_web/live/member_live/form.ex
@@ -1,4 +1,33 @@
 defmodule MvWeb.MemberLive.Form do
+  @moduledoc """
+  LiveView form for creating and editing members.
+
+  ## Features
+  - Create new members with personal information
+  - Edit existing member details
+  - Manage custom properties (dynamic fields)
+  - Real-time validation with visual feedback
+  - Link/unlink user accounts
+
+  ## Form Fields
+  **Required:**
+  - first_name, last_name, email
+
+  **Optional:**
+  - birth_date, phone_number, address fields (city, street, house_number, postal_code)
+  - join_date, exit_date
+  - paid status
+  - notes
+
+  ## Custom Properties
+  Members can have dynamic custom properties defined by PropertyTypes.
+  The form dynamically renders inputs based on available PropertyTypes.
+
+  ## Events
+  - `validate` - Real-time form validation
+  - `save` - Submit form (create or update member)
+  - Property management events for adding/removing custom fields
+  """
   use MvWeb, :live_view
 
   @impl true
diff --git a/lib/mv_web/live/member_live/index.ex b/lib/mv_web/live/member_live/index.ex
index e8c6d56..bfe2b8c 100644
--- a/lib/mv_web/live/member_live/index.ex
+++ b/lib/mv_web/live/member_live/index.ex
@@ -1,4 +1,29 @@
 defmodule MvWeb.MemberLive.Index do
+  @moduledoc """
+  LiveView for displaying and managing the member list.
+
+  ## Features
+  - Full-text search across member profiles using PostgreSQL tsvector
+  - Sortable columns (name, email, address fields)
+  - Bulk selection for future batch operations
+  - Real-time updates via LiveView
+  - Bookmarkable URLs with query parameters
+
+  ## URL Parameters
+  - `query` - Search query string for full-text search
+  - `sort_field` - Field to sort by (e.g., :first_name, :email, :join_date)
+  - `sort_order` - Sort direction (:asc or :desc)
+
+  ## Events
+  - `delete` - Remove a member from the database
+  - `select_member` - Toggle individual member selection
+  - `select_all` - Toggle selection of all visible members
+
+  ## Implementation Notes
+  - Search uses PostgreSQL full-text search (plainto_tsquery)
+  - Sort state is synced with URL for bookmarkability
+  - Components communicate via `handle_info` for decoupling
+  """
   use MvWeb, :live_view
   import Ash.Expr
   import Ash.Query
diff --git a/lib/mv_web/live/member_live/show.ex b/lib/mv_web/live/member_live/show.ex
index 9a0ef40..043915e 100644
--- a/lib/mv_web/live/member_live/show.ex
+++ b/lib/mv_web/live/member_live/show.ex
@@ -1,4 +1,26 @@
 defmodule MvWeb.MemberLive.Show do
+  @moduledoc """
+  LiveView for displaying a single member's details.
+
+  ## Features
+  - Display all member information (personal, contact, address)
+  - Show linked user account (if exists)
+  - Display custom properties
+  - Navigate to edit form
+  - Return to member list
+
+  ## Displayed Information
+  - Basic: name, email, dates (birth, join, exit)
+  - Contact: phone number
+  - Address: street, house number, postal code, city
+  - Status: paid flag
+  - Relationships: linked user account
+  - Custom: dynamic properties from PropertyTypes
+
+  ## Navigation
+  - Back to member list
+  - Edit member (with return_to parameter for back navigation)
+  """
   use MvWeb, :live_view
   import Ash.Query
 
diff --git a/lib/mv_web/live/property_live/form.ex b/lib/mv_web/live/property_live/form.ex
index a60a2e4..b85597d 100644
--- a/lib/mv_web/live/property_live/form.ex
+++ b/lib/mv_web/live/property_live/form.ex
@@ -1,4 +1,35 @@
 defmodule MvWeb.PropertyLive.Form do
+  @moduledoc """
+  LiveView form for creating and editing properties.
+
+  ## Features
+  - Create new properties with member and type selection
+  - Edit existing property values
+  - Value input adapts to property type (string, integer, boolean, date, email)
+  - Real-time validation
+
+  ## Form Fields
+  **Required:**
+  - member - Select which member owns this property
+  - property_type - Select the type (defines value type)
+  - value - The actual value (input type depends on property type)
+
+  ## Value Types
+  The form dynamically renders appropriate inputs based on property type:
+  - String: text input
+  - Integer: number input
+  - Boolean: checkbox
+  - Date: date picker
+  - Email: email input with validation
+
+  ## Events
+  - `validate` - Real-time form validation
+  - `save` - Submit form (create or update property)
+
+  ## Note
+  Properties are typically managed through the member edit form,
+  not through this standalone form.
+  """
   use MvWeb, :live_view
 
   @impl true
diff --git a/lib/mv_web/live/property_live/index.ex b/lib/mv_web/live/property_live/index.ex
index 70171ef..bc96bc0 100644
--- a/lib/mv_web/live/property_live/index.ex
+++ b/lib/mv_web/live/property_live/index.ex
@@ -1,4 +1,26 @@
 defmodule MvWeb.PropertyLive.Index do
+  @moduledoc """
+  LiveView for displaying and managing properties.
+
+  ## Features
+  - List all properties with their values and types
+  - Show which member each property belongs to
+  - Display property type information
+  - Navigate to property details and edit forms
+  - Delete properties
+
+  ## Relationships
+  Each property is linked to:
+  - A member (the property owner)
+  - A property type (defining value type and behavior)
+
+  ## Events
+  - `delete` - Remove a property from the database
+
+  ## Note
+  Properties are typically managed through the member edit form.
+  This view provides a global overview of all properties.
+  """
   use MvWeb, :live_view
 
   @impl true
diff --git a/lib/mv_web/live/property_live/show.ex b/lib/mv_web/live/property_live/show.ex
index 2a1e2ec..41e20c4 100644
--- a/lib/mv_web/live/property_live/show.ex
+++ b/lib/mv_web/live/property_live/show.ex
@@ -1,4 +1,24 @@
 defmodule MvWeb.PropertyLive.Show do
+  @moduledoc """
+  LiveView for displaying a single property's details.
+
+  ## Features
+  - Display property value and type
+  - Show linked member
+  - Show property type definition
+  - Navigate to edit form
+  - Return to property list
+
+  ## Displayed Information
+  - Property value (formatted based on type)
+  - Property type name and description
+  - Member information (who owns this property)
+  - Property metadata (ID, timestamps if added)
+
+  ## Navigation
+  - Back to property list
+  - Edit property
+  """
   use MvWeb, :live_view
 
   @impl true
diff --git a/lib/mv_web/live/property_type_live/form.ex b/lib/mv_web/live/property_type_live/form.ex
index 8b8b452..292de2b 100644
--- a/lib/mv_web/live/property_type_live/form.ex
+++ b/lib/mv_web/live/property_type_live/form.ex
@@ -1,4 +1,38 @@
 defmodule MvWeb.PropertyTypeLive.Form do
+  @moduledoc """
+  LiveView form for creating and editing property types (admin).
+
+  ## Features
+  - Create new property type definitions
+  - Edit existing property types
+  - Select value type from supported types
+  - Set immutable and required flags
+  - Real-time validation
+
+  ## Form Fields
+  **Required:**
+  - name - Unique identifier (e.g., "phone_mobile", "emergency_contact")
+  - value_type - Data type (:string, :integer, :boolean, :date, :email)
+
+  **Optional:**
+  - description - Human-readable explanation
+  - immutable - If true, values cannot be changed after creation (default: false)
+  - required - If true, all members must have this property (default: false)
+
+  ## Value Type Selection
+  - `:string` - Text data (unlimited length)
+  - `:integer` - Numeric data
+  - `:boolean` - True/false flags
+  - `:date` - Date values
+  - `:email` - Validated email addresses
+
+  ## Events
+  - `validate` - Real-time form validation
+  - `save` - Submit form (create or update property type)
+
+  ## Security
+  Property type management is restricted to admin users.
+  """
   use MvWeb, :live_view
 
   @impl true
diff --git a/lib/mv_web/live/property_type_live/index.ex b/lib/mv_web/live/property_type_live/index.ex
index dae4da0..2731414 100644
--- a/lib/mv_web/live/property_type_live/index.ex
+++ b/lib/mv_web/live/property_type_live/index.ex
@@ -1,4 +1,28 @@
 defmodule MvWeb.PropertyTypeLive.Index do
+  @moduledoc """
+  LiveView for managing property type definitions (admin).
+
+  ## Features
+  - List all property types
+  - Display type information (name, value type, description)
+  - Show immutable and required flags
+  - Create new property types
+  - Edit existing property types
+  - Delete property types (if no properties use them)
+
+  ## Displayed Information
+  - Name: Unique identifier for the property type
+  - Value type: Data type constraint (string, integer, boolean, date, email)
+  - Description: Human-readable explanation
+  - Immutable: Whether property values can be changed after creation
+  - Required: Whether all members must have this property (future feature)
+
+  ## Events
+  - `delete` - Remove a property type (only if no properties exist)
+
+  ## Security
+  Property type management is restricted to admin users.
+  """
   use MvWeb, :live_view
 
   @impl true
diff --git a/lib/mv_web/live/property_type_live/show.ex b/lib/mv_web/live/property_type_live/show.ex
index ec2b0bf..b5c441c 100644
--- a/lib/mv_web/live/property_type_live/show.ex
+++ b/lib/mv_web/live/property_type_live/show.ex
@@ -1,4 +1,27 @@
 defmodule MvWeb.PropertyTypeLive.Show do
+  @moduledoc """
+  LiveView for displaying a single property type's details (admin).
+
+  ## Features
+  - Display property type definition
+  - Show all attributes (name, value type, description, flags)
+  - Navigate to edit form
+  - Return to property type list
+
+  ## Displayed Information
+  - Name: Unique identifier
+  - Value type: Data type constraint
+  - Description: Optional explanation
+  - Immutable flag: Whether values can be changed
+  - Required flag: Whether all members need this property
+
+  ## Navigation
+  - Back to property type list
+  - Edit property type
+
+  ## Security
+  Property type details are restricted to admin users.
+  """
   use MvWeb, :live_view
 
   @impl true
diff --git a/lib/mv_web/live/user_live/form.ex b/lib/mv_web/live/user_live/form.ex
index c7fd2d0..cf7b687 100644
--- a/lib/mv_web/live/user_live/form.ex
+++ b/lib/mv_web/live/user_live/form.ex
@@ -1,4 +1,36 @@
 defmodule MvWeb.UserLive.Form do
+  @moduledoc """
+  LiveView form for creating and editing users.
+
+  ## Features
+  - Create new users with email
+  - Edit existing user details
+  - Optional password setting (checkbox to toggle)
+  - Link/unlink member accounts
+  - Email synchronization with linked members
+
+  ## Form Fields
+  **Required:**
+  - email
+
+  **Optional:**
+  - password (for password authentication strategy)
+  - linked member (select from existing members)
+
+  ## Password Management
+  - New users: Can optionally set password with confirmation
+  - Existing users: Can change password (no confirmation required, admin action)
+  - Checkbox toggles password section visibility
+
+  ## Member Linking
+  Users can be linked to existing member accounts. When linked, emails are
+  synchronized bidirectionally with User.email as the source of truth.
+
+  ## Events
+  - `validate` - Real-time form validation
+  - `save` - Submit form (create or update user)
+  - `toggle_password_section` - Show/hide password fields
+  """
   use MvWeb, :live_view
 
   @impl true
diff --git a/lib/mv_web/live/user_live/index.ex b/lib/mv_web/live/user_live/index.ex
index 39ced23..8803237 100644
--- a/lib/mv_web/live/user_live/index.ex
+++ b/lib/mv_web/live/user_live/index.ex
@@ -1,4 +1,25 @@
 defmodule MvWeb.UserLive.Index do
+  @moduledoc """
+  LiveView for displaying and managing the user list.
+
+  ## Features
+  - List all users with email and linked member
+  - Sort users by email (default)
+  - Delete users
+  - Navigate to user details and edit forms
+  - Bulk selection for future batch operations
+
+  ## Relationships
+  Displays linked member information when a user is connected to a member account.
+
+  ## Events
+  - `delete` - Remove a user from the database
+  - `select_user` - Toggle individual user selection
+  - `select_all` - Toggle selection of all visible users
+
+  ## Security
+  User deletion requires admin permissions (enforced by Ash policies).
+  """
   use MvWeb, :live_view
   import MvWeb.TableComponents
 
diff --git a/lib/mv_web/live/user_live/show.ex b/lib/mv_web/live/user_live/show.ex
index bdd241b..664f99f 100644
--- a/lib/mv_web/live/user_live/show.ex
+++ b/lib/mv_web/live/user_live/show.ex
@@ -1,4 +1,29 @@
 defmodule MvWeb.UserLive.Show do
+  @moduledoc """
+  LiveView for displaying a single user's details.
+
+  ## Features
+  - Display user information (email, OIDC ID)
+  - Show authentication methods (password, OIDC)
+  - Display linked member account (if exists)
+  - Navigate to edit form
+  - Return to user list
+
+  ## Displayed Information
+  - Email address
+  - OIDC ID (if authenticated via OIDC)
+  - Password authentication status
+  - Linked member (name and email)
+
+  ## Authentication Status
+  Shows which authentication methods are enabled for the user:
+  - Password authentication (has hashed_password)
+  - OIDC authentication (has oidc_id)
+
+  ## Navigation
+  - Back to user list
+  - Edit user (with return_to parameter for back navigation)
+  """
   use MvWeb, :live_view
 
   @impl true