fix: add @moduledoc to all public modules (CSM-018)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CODESMELL.md

@@ -307,9 +307,22 @@
 
 ## Low Severity / Code Quality
 
-### CSM-018 — `@moduledoc false` Epidemic
+### ~~CSM-018 — `@moduledoc false` Epidemic~~ ✅ FIXED
-- **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`
+- **Fixed:** 2026-05-10
-- **Fix:** Write `@moduledoc` descriptions for all public modules. Keep internal helpers documented or mark them `@moduledoc false` only if truly private.
+- **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
 
 ---
 

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

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

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

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"},

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
 

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()}

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

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
 

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"
 

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

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

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]