From 7375b8316790074a5cf6daeb2c0c17649a8d19f8 Mon Sep 17 00:00:00 2001 From: Moritz Date: Mon, 10 Nov 2025 16:36:48 +0100 Subject: [PATCH] docs: add @doc to public functions in EmailSync, Validations, and Senders Document public API functions with @doc for better tooling support: - EmailSync Changes: sync_user_email_to_member, sync_member_email_to_user - Validations: email_not_used_by_other_member, email_not_used_by_other_user - Senders: send_new_user_confirmation_email, send_password_reset_email --- .../senders/send_new_user_confirmation_email.ex | 14 ++++++++++++++ .../user/senders/send_password_reset_email.ex | 14 ++++++++++++++ .../email_not_used_by_other_member.ex | 16 ++++++++++++++++ .../changes/sync_member_email_to_user.ex | 15 +++++++++++++++ .../changes/sync_user_email_to_member.ex | 15 +++++++++++++++ .../validations/email_not_used_by_other_user.ex | 16 ++++++++++++++++ 6 files changed, 90 insertions(+) diff --git a/lib/mv/accounts/user/senders/send_new_user_confirmation_email.ex b/lib/mv/accounts/user/senders/send_new_user_confirmation_email.ex index 9e34f29..2135465 100644 --- a/lib/mv/accounts/user/senders/send_new_user_confirmation_email.ex +++ b/lib/mv/accounts/user/senders/send_new_user_confirmation_email.ex @@ -10,6 +10,20 @@ defmodule Mv.Accounts.User.Senders.SendNewUserConfirmationEmail do alias Mv.Mailer + @doc """ + Sends a confirmation email to a new user. + + This function is called automatically by AshAuthentication when a new + user registers and needs to confirm their email address. + + ## Parameters + - `user` - The user record who needs to confirm their email + - `token` - The confirmation token to include in the email link + - `_opts` - Additional options (unused) + + ## Returns + The Swoosh.Email delivery result from `Mailer.deliver!/1`. + """ @impl true def send(user, token, _) do new() diff --git a/lib/mv/accounts/user/senders/send_password_reset_email.ex b/lib/mv/accounts/user/senders/send_password_reset_email.ex index 7c33d2e..bcf4e75 100644 --- a/lib/mv/accounts/user/senders/send_password_reset_email.ex +++ b/lib/mv/accounts/user/senders/send_password_reset_email.ex @@ -10,6 +10,20 @@ defmodule Mv.Accounts.User.Senders.SendPasswordResetEmail do alias Mv.Mailer + @doc """ + Sends a password reset email to a user. + + This function is called automatically by AshAuthentication when a user + requests a password reset. + + ## Parameters + - `user` - The user record requesting the password reset + - `token` - The password reset token to include in the email link + - `_opts` - Additional options (unused) + + ## Returns + The Swoosh.Email delivery result from `Mailer.deliver!/1`. + """ @impl true def send(user, token, _) do new() diff --git a/lib/mv/accounts/user/validations/email_not_used_by_other_member.ex b/lib/mv/accounts/user/validations/email_not_used_by_other_member.ex index d42b2c1..9cea265 100644 --- a/lib/mv/accounts/user/validations/email_not_used_by_other_member.ex +++ b/lib/mv/accounts/user/validations/email_not_used_by_other_member.ex @@ -9,6 +9,22 @@ defmodule Mv.Accounts.User.Validations.EmailNotUsedByOtherMember do """ use Ash.Resource.Validation + @doc """ + Validates email uniqueness across linked User-Member pairs. + + This validation ensures that when a user is linked to a member, their email + does not conflict with another member's email. It only runs when necessary + to avoid blocking valid operations (see `@moduledoc` for trigger conditions). + + ## Parameters + - `changeset` - The Ash changeset being validated + - `_opts` - Options passed to the validation (unused) + - `_context` - Ash context map (unused) + + ## Returns + - `:ok` if validation passes or should be skipped + - `{:error, field: :email, message: ..., value: ...}` if validation fails + """ @impl true def validate(changeset, _opts, _context) do email_changing? = Ash.Changeset.changing_attribute?(changeset, :email) diff --git a/lib/mv/email_sync/changes/sync_member_email_to_user.ex b/lib/mv/email_sync/changes/sync_member_email_to_user.ex index c1e5aea..48c7955 100644 --- a/lib/mv/email_sync/changes/sync_member_email_to_user.ex +++ b/lib/mv/email_sync/changes/sync_member_email_to_user.ex @@ -10,6 +10,21 @@ defmodule Mv.EmailSync.Changes.SyncMemberEmailToUser do use Ash.Resource.Change alias Mv.EmailSync.{Helpers, Loader} + @doc """ + Implements the email synchronization from Member to User. + + This function is called automatically by Ash when the configured trigger + conditions are met (see `@moduledoc` for trigger details). + + ## Parameters + - `changeset` - The Ash changeset being processed + - `_opts` - Options passed to the change (unused) + - `context` - Ash context map containing metadata (e.g., `:syncing_email` flag) + + ## Returns + Modified changeset with email synchronization applied, or original changeset + if recursion detected. + """ @impl true def change(changeset, _opts, context) do # Only recursion protection needed - trigger logic is in `where` clauses diff --git a/lib/mv/email_sync/changes/sync_user_email_to_member.ex b/lib/mv/email_sync/changes/sync_user_email_to_member.ex index be7dd2c..7148067 100644 --- a/lib/mv/email_sync/changes/sync_user_email_to_member.ex +++ b/lib/mv/email_sync/changes/sync_user_email_to_member.ex @@ -12,6 +12,21 @@ defmodule Mv.EmailSync.Changes.SyncUserEmailToMember do use Ash.Resource.Change alias Mv.EmailSync.{Helpers, Loader} + @doc """ + Implements the email synchronization from User to Member. + + This function is called automatically by Ash when the configured trigger + conditions are met (see `@moduledoc` for trigger details). + + ## Parameters + - `changeset` - The Ash changeset being processed + - `_opts` - Options passed to the change (unused) + - `context` - Ash context map containing metadata (e.g., `:syncing_email` flag) + + ## Returns + Modified changeset with email synchronization applied, or original changeset + if recursion detected. + """ @impl true def change(changeset, _opts, context) do # Only recursion protection needed - trigger logic is in `where` clauses diff --git a/lib/mv/membership/member/validations/email_not_used_by_other_user.ex b/lib/mv/membership/member/validations/email_not_used_by_other_user.ex index 54fa243..a14bc0b 100644 --- a/lib/mv/membership/member/validations/email_not_used_by_other_user.ex +++ b/lib/mv/membership/member/validations/email_not_used_by_other_user.ex @@ -9,6 +9,22 @@ defmodule Mv.Membership.Member.Validations.EmailNotUsedByOtherUser do """ use Ash.Resource.Validation + @doc """ + Validates email uniqueness across linked Member-User pairs. + + This validation ensures that when a member is linked to a user, their email + does not conflict with another user's email. It only runs when necessary + to avoid blocking valid operations (see `@moduledoc` for trigger conditions). + + ## Parameters + - `changeset` - The Ash changeset being validated + - `_opts` - Options passed to the validation (unused) + - `_context` - Ash context map (unused) + + ## Returns + - `:ok` if validation passes or should be skipped + - `{:error, field: :email, message: ..., value: ...}` if validation fails + """ @impl true def validate(changeset, _opts, _context) do email_changing? = Ash.Changeset.changing_attribute?(changeset, :email)