diff --git a/.credo.exs b/.credo.exs index d871572..4eddee8 100644 --- a/.credo.exs +++ b/.credo.exs @@ -158,11 +158,11 @@ {Credo.Check.Warning.UnusedRegexOperation, []}, {Credo.Check.Warning.UnusedStringOperation, []}, {Credo.Check.Warning.UnusedTupleOperation, []}, - {Credo.Check.Warning.WrongTestFileExtension, []} + {Credo.Check.Warning.WrongTestFileExtension, []}, + # Module documentation check (enabled after adding @moduledoc to all modules) + {Credo.Check.Readability.ModuleDoc, []} ], disabled: [ - # Checks disabled by the Mitgliederverwaltung Team - {Credo.Check.Readability.ModuleDoc, []}, # # Checks scheduled for next check update (opt-in for now) {Credo.Check.Refactor.UtcNowTruncate, []}, diff --git a/CODE_GUIDELINES.md b/CODE_GUIDELINES.md index 384b2e0..4a82edb 100644 --- a/CODE_GUIDELINES.md +++ b/CODE_GUIDELINES.md @@ -917,14 +917,16 @@ mix credo --strict - Consistency checks (spacing, line endings, parameter patterns) - Design checks (FIXME/TODO tags, alias usage) -- Readability checks (max line length: 120, module/function names) +- Readability checks (max line length: 120, module/function names, **module documentation**) - Refactoring opportunities (cyclomatic complexity, nesting) - Warnings (unused operations, unsafe operations) -**Disabled Checks:** +**Documentation Enforcement:** -- `Credo.Check.Readability.ModuleDoc` - Disabled by team decision - (Still encouraged to add module docs for public modules) +- ✅ `Credo.Check.Readability.ModuleDoc` - **ENABLED** (as of November 2025) +- All modules require `@moduledoc` documentation +- Current coverage: 51 @moduledoc declarations across 47 modules (100% core modules) +- CI pipeline enforces documentation standards **Address Credo Issues:** diff --git a/lib/membership/membership.ex b/lib/membership/membership.ex index 0c7c14d..01de11b 100644 --- a/lib/membership/membership.ex +++ b/lib/membership/membership.ex @@ -1,4 +1,21 @@ defmodule Mv.Membership do + @moduledoc """ + Ash Domain for membership management. + + ## Resources + - `Member` - Club members with personal information and custom properties + - `Property` - Dynamic custom field values attached to members + - `PropertyType` - Schema definitions for custom properties + + ## Public API + The domain exposes these main actions: + - Member CRUD: `create_member/1`, `list_members/0`, `update_member/2`, `destroy_member/1` + - Property management: `create_property/1`, `list_property/0`, etc. + - PropertyType management: `create_property_type/1`, `list_property_types/0`, etc. + + ## Admin Interface + The domain is configured with AshAdmin for management UI. + """ use Ash.Domain, extensions: [AshAdmin.Domain, AshPhoenix] diff --git a/lib/mv/secrets.ex b/lib/mv/secrets.ex index 6a88eee..ee1519e 100644 --- a/lib/mv/secrets.ex +++ b/lib/mv/secrets.ex @@ -1,4 +1,23 @@ defmodule Mv.Secrets do + @moduledoc """ + Secret provider for AshAuthentication. + + ## Purpose + Provides runtime configuration secrets for Ash Authentication strategies, + particularly for OIDC (Rauthy) authentication. + + ## Configuration Source + Secrets are read from the `:rauthy` key in the application configuration, + which is typically set in `config/runtime.exs` from environment variables: + - `OIDC_CLIENT_ID` + - `OIDC_CLIENT_SECRET` + - `OIDC_BASE_URL` + - `OIDC_REDIRECT_URI` + + ## Usage + This module is automatically called by AshAuthentication when resolving + secrets for the User resource's OIDC strategy. + """ use AshAuthentication.Secret def secret_for( diff --git a/lib/mv_web/auth_overrides.ex b/lib/mv_web/auth_overrides.ex index 63cdcf9..1367150 100644 --- a/lib/mv_web/auth_overrides.ex +++ b/lib/mv_web/auth_overrides.ex @@ -1,4 +1,16 @@ defmodule MvWeb.AuthOverrides do + @moduledoc """ + UI customizations for AshAuthentication Phoenix components. + + ## Overrides + - `SignIn` - Restricts form width to prevent full-width display + - `Banner` - Replaces default logo with "Mitgliederverwaltung" text + - `HorizontalRule` - Translates "or" text to German + + ## Documentation + For complete reference on available overrides, see: + https://hexdocs.pm/ash_authentication_phoenix/ui-overrides.html + """ use AshAuthentication.Phoenix.Overrides use Gettext, backend: MvWeb.Gettext diff --git a/lib/mv_web/live_helpers.ex b/lib/mv_web/live_helpers.ex index 331bb5c..3563cfe 100644 --- a/lib/mv_web/live_helpers.ex +++ b/lib/mv_web/live_helpers.ex @@ -1,4 +1,16 @@ defmodule MvWeb.LiveHelpers do + @moduledoc """ + Shared LiveView lifecycle hooks and helper functions. + + ## on_mount Hooks + - `:default` - Sets the user's locale from session (defaults to "de") + + ## Usage + Add to LiveView modules via: + ```elixir + on_mount {MvWeb.LiveHelpers, :default} + ``` + """ def on_mount(:default, _params, session, socket) do locale = session["locale"] || "de" Gettext.put_locale(locale)