From 3f77488e3329fd2a1f70982a5ec85c3f7f767b44 Mon Sep 17 00:00:00 2001 From: Chili Palmer Date: Sun, 10 May 2026 11:30:08 +0200 Subject: [PATCH] fix: add @moduledoc to all public modules (CSM-018) Co-Authored-By: Claude Opus 4.6 --- CODESMELL.md | 19 ++++++++++++++++--- lib/bds/ai.ex | 5 ++++- lib/bds/bounded_atoms.ex | 5 ++++- lib/bds/document_fields.ex | 5 ++++- lib/bds/i18n.ex | 4 +++- lib/bds/import_definitions.ex | 5 ++++- lib/bds/map_utils.ex | 5 ++++- lib/bds/mcp.ex | 5 ++++- lib/bds/publishing.ex | 5 ++++- lib/bds/scripting/api_docs.ex | 5 ++++- lib/bds/scripting/capabilities.ex | 5 ++++- lib/bds/settings.ex | 4 +++- lib/bds/templates.ex | 5 ++++- 13 files changed, 62 insertions(+), 15 deletions(-) diff --git a/CODESMELL.md b/CODESMELL.md index c6f5527..c163fa7 100644 --- a/CODESMELL.md +++ b/CODESMELL.md @@ -307,9 +307,22 @@ ## Low Severity / Code Quality -### CSM-018 — `@moduledoc false` Epidemic -- **Files:** `lib/bds/i18n.ex`, `lib/bds/map_utils.ex`, `lib/bds/bounded_atoms.ex`, `lib/bds/document_fields.ex`, `lib/bds/import_definitions.ex`, `lib/bds/publishing.ex`, `lib/bds/settings.ex`, `lib/bds/templates.ex`, `lib/bds/ai.ex`, `lib/bds/mcp.ex`, `lib/bds/scripting/capabilities.ex`, `lib/bds/scripting/api_docs.ex` -- **Fix:** Write `@moduledoc` descriptions for all public modules. Keep internal helpers documented or mark them `@moduledoc false` only if truly private. +### ~~CSM-018 — `@moduledoc false` Epidemic~~ ✅ FIXED +- **Fixed:** 2026-05-10 +- **What was done:** + - Replaced `@moduledoc false` with descriptive `@moduledoc` strings in all 12 listed public modules: + - `lib/bds/i18n.ex` — language support, locale resolution, flag emoji mapping + - `lib/bds/map_utils.ex` — mixed-key map utilities and safe atom conversion + - `lib/bds/bounded_atoms.ex` — allow-list-based dynamic atom conversion + - `lib/bds/document_fields.ex` — frontmatter field access with key aliases + - `lib/bds/import_definitions.ex` — CRUD for WXR import configurations + - `lib/bds/publishing.ex` — GenServer for site upload job coordination + - `lib/bds/settings.ex` — global key-value settings persistence + - `lib/bds/templates.ex` — Liquid template lifecycle management + - `lib/bds/ai.ex` — AI endpoint config, secrets, and inference dispatch + - `lib/bds/mcp.ex` — MCP server facade for external AI agents + - `lib/bds/scripting/capabilities.ex` — Lua scripting capability map builder + - `lib/bds/scripting/api_docs.ex` — machine-readable Lua API documentation --- diff --git a/lib/bds/ai.ex b/lib/bds/ai.ex index b6d685d..e049d3f 100644 --- a/lib/bds/ai.ex +++ b/lib/bds/ai.ex @@ -1,5 +1,8 @@ defmodule BDS.AI do - @moduledoc false + @moduledoc """ + Public interface for AI features — endpoint configuration, secret management, + model catalog access, and dispatching chat and one-shot inference requests. + """ alias BDS.AI.Catalog alias BDS.AI.Chat diff --git a/lib/bds/bounded_atoms.ex b/lib/bds/bounded_atoms.ex index 9cd26d1..816de22 100644 --- a/lib/bds/bounded_atoms.ex +++ b/lib/bds/bounded_atoms.ex @@ -1,5 +1,8 @@ defmodule BDS.BoundedAtoms do - @moduledoc false + @moduledoc """ + Safe conversion of dynamic values to atoms from pre-defined allow-lists, + preventing atom table exhaustion from untrusted input. + """ alias BDS.UI.Registry alias BDS.UI.MenuBar diff --git a/lib/bds/document_fields.ex b/lib/bds/document_fields.ex index 606a1b4..e70b259 100644 --- a/lib/bds/document_fields.ex +++ b/lib/bds/document_fields.ex @@ -1,5 +1,8 @@ defmodule BDS.DocumentFields do - @moduledoc false + @moduledoc """ + Accessor functions for document frontmatter fields, supporting key aliases + (e.g. "date" and "published_at" resolve to the same value). + """ def get(fields, key, default \\ nil) when is_map(fields) and is_binary(key) do case fetch(fields, key) do diff --git a/lib/bds/i18n.ex b/lib/bds/i18n.ex index e295840..ca69925 100644 --- a/lib/bds/i18n.ex +++ b/lib/bds/i18n.ex @@ -1,5 +1,7 @@ defmodule BDS.I18n do - @moduledoc false + @moduledoc """ + Internationalization helpers for supported languages, locale resolution, and flag emoji mapping. + """ @supported_languages [ %{code: "en", flag: "GB"}, diff --git a/lib/bds/import_definitions.ex b/lib/bds/import_definitions.ex index 28812f2..457663f 100644 --- a/lib/bds/import_definitions.ex +++ b/lib/bds/import_definitions.ex @@ -1,5 +1,8 @@ defmodule BDS.ImportDefinitions do - @moduledoc false + @moduledoc """ + CRUD operations for import definitions — saved configurations for importing + content from WordPress WXR exports. + """ import Ecto.Query diff --git a/lib/bds/map_utils.ex b/lib/bds/map_utils.ex index 6e39152..7d1c33e 100644 --- a/lib/bds/map_utils.ex +++ b/lib/bds/map_utils.ex @@ -1,5 +1,8 @@ defmodule BDS.MapUtils do - @moduledoc false + @moduledoc """ + Utility functions for working with maps that may have atom or string keys, + including safe atom conversion for untrusted input. + """ @typedoc "An attribute map that may use atom or string keys." @type attrs :: %{optional(atom()) => term(), optional(String.t()) => term()} diff --git a/lib/bds/mcp.ex b/lib/bds/mcp.ex index 274c829..5456c5b 100644 --- a/lib/bds/mcp.ex +++ b/lib/bds/mcp.ex @@ -1,5 +1,8 @@ defmodule BDS.MCP do - @moduledoc false + @moduledoc """ + Facade for the Model Context Protocol server, exposing tools and resources + that external AI agents can invoke to read and manipulate blog content. + """ alias BDS.MCP.Resources alias BDS.MCP.Tools diff --git a/lib/bds/publishing.ex b/lib/bds/publishing.ex index 2fc4e76..5cf2f25 100644 --- a/lib/bds/publishing.ex +++ b/lib/bds/publishing.ex @@ -1,5 +1,8 @@ defmodule BDS.Publishing do - @moduledoc false + @moduledoc """ + GenServer that manages site upload jobs, coordinating file transfers to + configured hosting destinations and tracking progress via the task system. + """ use GenServer diff --git a/lib/bds/scripting/api_docs.ex b/lib/bds/scripting/api_docs.ex index c7f8d43..4a38346 100644 --- a/lib/bds/scripting/api_docs.ex +++ b/lib/bds/scripting/api_docs.ex @@ -1,5 +1,8 @@ defmodule BDS.Scripting.ApiDocs do - @moduledoc false + @moduledoc """ + Machine-readable documentation for the Lua scripting API, used to generate + help text, autocompletion data, and the published API reference. + """ @version "0.4.0" diff --git a/lib/bds/scripting/capabilities.ex b/lib/bds/scripting/capabilities.ex index 5aa5af9..e06b15d 100644 --- a/lib/bds/scripting/capabilities.ex +++ b/lib/bds/scripting/capabilities.ex @@ -1,5 +1,8 @@ defmodule BDS.Scripting.Capabilities do - @moduledoc false + @moduledoc """ + Builds the capability map exposed to Lua scripts, binding each scripting API + method to its Elixir implementation for a given project context. + """ alias BDS.I18n alias BDS.Tasks diff --git a/lib/bds/settings.ex b/lib/bds/settings.ex index 6f81777..afc8b8d 100644 --- a/lib/bds/settings.ex +++ b/lib/bds/settings.ex @@ -1,5 +1,7 @@ defmodule BDS.Settings do - @moduledoc false + @moduledoc """ + Persistence layer for global application settings stored as key-value pairs in the database. + """ alias BDS.Persistence alias BDS.Repo diff --git a/lib/bds/templates.ex b/lib/bds/templates.ex index 1d6c8aa..251216d 100644 --- a/lib/bds/templates.ex +++ b/lib/bds/templates.ex @@ -1,5 +1,8 @@ defmodule BDS.Templates do - @moduledoc false + @moduledoc """ + CRUD and lifecycle management for Liquid templates (posts, lists, partials, 404 pages), + including slug derivation, status transitions, and filesystem synchronization. + """ import Ecto.Query import BDS.MapUtils, only: [attr: 2, maybe_put: 3]