elixir-writing-docs

Elixir Writing Docs

Quick Reference

Topic	Reference
Doctests: syntax, gotchas, when to use	references/doctests.md
Cross-references and linking syntax	references/cross-references.md
Admonitions, formatting, tabs	references/admonitions-and-formatting.md

First-Line Summary Rule

ExDoc and tools like mix docs extract the first paragraph of @moduledoc and @doc as a summary. Keep the opening line concise and self-contained.

# GOOD - first line works as a standalone summary
@moduledoc """
Handles payment processing through Stripe and local ledger reconciliation.

Wraps the Stripe API client and ensures each charge is recorded in the
local ledger before returning a confirmation to the caller.
"""

# BAD - first line is vague, forces reader to continue
@moduledoc """
This module contains various functions related to payments.

It uses Stripe and also updates the ledger.
"""

The same rule applies to @doc:

# GOOD
@doc """
Charges a customer's default payment method for the given amount in cents.

Returns `{:ok, charge}` on success or `{:error, reason}` when the payment
gateway rejects the request.
"""

# BAD
@doc """
This function is used to charge a customer.
"""

@moduledoc Structure

A well-structured @moduledoc follows this pattern:

defmodule MyApp.Inventory do
  @moduledoc """
  Tracks warehouse stock levels and triggers replenishment orders.

  This module maintains an ETS-backed cache of current quantities and
  exposes functions for atomic stock adjustments. It is designed to be
  started under a supervisor and will restore state from the database
  on init.

  ## Examples

      iex> {:ok, pid} = MyApp.Inventory.start_link(warehouse: :east)
      iex> MyApp.Inventory.current_stock(pid, "SKU-1042")
      {:ok, 350}

  ## Configuration

  Expects the following in `config/runtime.exs`:

      config :my_app, MyApp.Inventory,
        repo: MyApp.Repo,
        low_stock_threshold: 50
  """
end