Skip to content

existential-birds/beagle / plugins/beagle-elixir/skills/elixir-writing-docs

elixir-writing-docs

Verified

Guides writing Elixir documentation with @moduledoc, @doc, @typedoc, doctests, cross-references, and metadata. Use when adding or improving documentation in .ex files.

FileKindSize
SKILL.mdskill md9.0 KB
references/admonitions-and-formatting.mdmarkdown7.1 KB
references/cross-references.mdmarkdown4.3 KB
references/doctests.mdmarkdown6.8 KB

references/admonitions-and-formatting.md

View on GitHub
# Admonitions and Formatting

## Admonition Blocks

Admonitions are callout boxes rendered by ExDoc. They use blockquote syntax with a special heading:

```markdown
> #### Watch out for atom exhaustion {: .warning}
>
> Calling `String.to_atom/1` on user input can exhaust the atom table.
> Use `String.to_existing_atom/1` instead.
```

### Structure

1. Start with `> ####` followed by the admonition title
2. Add `{: .class}` at the end of the title line
3. Follow with `>` blank line and `>` content lines

### Available Classes

| Class | Use for | Rendered appearance |
|-------|---------|---------------------|
| `.warning` | Potential pitfalls, breaking changes | Yellow/amber box |
| `.error` | Dangerous operations, common mistakes | Red box |
| `.info` | Additional context, background | Blue box |
| `.tip` | Best practices, performance hints | Green box |
| `.neutral` | General callouts without urgency | Grey box |

### Examples

```elixir
@moduledoc """
Manages database connections for the application.

> #### Requires database access {: .info}
>
> This module expects a running PostgreSQL instance. See the
> [setup guide](setup.md) for local development configuration.

> #### Connection pooling {: .tip}
>
> For high-throughput workloads, increase the pool size in
> `config/runtime.exs`:
>
>     config :my_app, MyApp.Repo,
>       pool_size: 20

> #### Do not call at compile time {: .error}
>
> Functions in this module require the application to be started.
> Calling them in module attributes or at compile time will raise.
"""
```

### Multi-Paragraph Admonitions

Continue with `>` on each line:

```elixir
@doc """
> #### Migration required {: .warning}
>
> After upgrading to v2.0, run the following migration:
>
>     mix ecto.migrate
>
> This adds the `archived_at` column used by the new soft-delete
> feature. Existing rows will have `NULL` in this column, which
> the query functions treat as "not archived."
"""
```

## Heading Levels

In `@moduledoc` and `@doc`, use **second-level headings** (`##`) as the highest level. First-level headings (`#`) are reserved for the module or function name in ExDoc output.

```elixir
# GOOD
@moduledoc """
Handles webhook delivery and retry logic.

## Retry Strategy

Failed deliveries are retried with exponential backoff.

## Configuration

Set the maximum retry count in your config.
"""

# BAD - # will clash with ExDoc's page title
@moduledoc """
# Webhook Delivery

Handles webhook delivery and retry logic.
"""
```

Within reference documentation and extra pages, `#` is acceptable as a page title.

## Tabbed Content

ExDoc supports tabbed content blocks using HTML comments and third-level headings:

```elixir
@moduledoc """
## Installation

<!-- tabs-open -->

### Mix

Add to your `mix.exs` dependencies:

    {:my_library, "~> 1.0"}

### Rebar3

Add to your `rebar.config`:

    {deps, [{my_library, "1.0.0"}]}.

### Erlang.mk

Add to your `Makefile`:

    dep_my_library = hex 1.0.0

<!-- tabs-close -->
"""
```

**Rules:**

- Open with `<!-- tabs-open -->`
- Each tab is a `###` heading
- Close with `<!-- tabs-close -->`
- Content between `###` headings becomes that tab's body
- Tabs work in `@moduledoc`, `@doc`, and extra pages

### Realistic Example

```elixir
@doc """
Serializes a struct to a transport format.

## Examples

<!-- tabs-open -->

### JSON

    iex> MyApp.Serializer.encode(%User{name: "Alice"}, :json)
    {:ok, ~s({"name":"Alice"})}

### MessagePack

    iex> MyApp.Serializer.encode(%User{name: "Alice"}, :msgpack)
    {:ok, <<129, 164, 110, 97, 109, 101, 165, 65, 108, 105, 99, 101>>}

<!-- tabs-close -->
"""
```

## Code Blocks

Use fenced code blocks with a language tag for syntax highlighting:

````elixir
@moduledoc """
## Usage

```elixir
{:ok, conn} = MyApp.Connection.open("localhost", 5432)
MyApp.Connection.query(conn, "SELECT 1")
```

Configuration in `config/runtime.exs`:

```elixir
config :my_app, MyApp.Connection,
  hostname: System.get_env("DB_HOST", "localhost"),
  port: String.to_integer(System.get_env("DB_PORT", "5432"))
```
"""
````

For shell commands:

````elixir
@moduledoc """
## Getting Started

```bash
mix deps.get
mix ecto.setup
mix phx.server
```
"""
````

### Indented Code Blocks in Doctests

Within `## Examples` sections, use four-space indentation (not fenced blocks) so that ExDoc can detect and run doctests:

```elixir
@doc """
## Examples

    iex> MyApp.Math.add(2, 3)
    5
"""
```

## Lists

### Unordered Lists

```elixir
@doc """
Supported formats:

* `:json` - JSON encoding via Jason
* `:msgpack` - MessagePack via Msgpax
* `:csv` - CSV encoding via NimbleCSV
"""
```

### Ordered Lists

```elixir
@doc """
Processing pipeline:

1. Validate input against the schema
2. Transform to internal representation
3. Persist to the database
4. Broadcast change event
"""
```

### Nested Lists

```elixir
@doc """
Options:

* `:format` - Output format
  * `:json` - Default
  * `:csv` - Comma-separated
* `:compress` - Whether to gzip the output
  * `true` - Enable compression
  * `false` - Default, no compression
"""
```

## Tables

```elixir
@moduledoc """
## HTTP Status Mapping

| Status | Atom | Description |
|--------|------|-------------|
| 200 | `:ok` | Successful request |
| 201 | `:created` | Resource created |
| 400 | `:bad_request` | Invalid input |
| 404 | `:not_found` | Resource missing |
| 422 | `:unprocessable_entity` | Validation failed |
"""
```

Tables must have a header row and a separator row. Alignment colons (`:---`, `:---:`, `---:`) are supported.

## Inline Formatting

| Syntax | Renders as | Use for |
|--------|-----------|---------|
| `` `code` `` | `code` | Module names, functions, atoms, options |
| `**bold**` | **bold** | Emphasis on key terms |
| `*italic*` | *italic* | Titles, introducing terms |
| `[text](url)` | link | External URLs |
| `` [`text`](`Module`) `` | code link | Cross-references (see cross-references.md) |

## Combining Formatting Techniques

A well-formatted `@moduledoc` uses several of these elements together:

```elixir
defmodule MyApp.RateLimiter do
  @moduledoc """
  Token-bucket rate limiter backed by ETS.

  Limits are configured per endpoint and enforced in the
  `MyApp.Plugs.RateLimit` plug.

  > #### Production configuration {: .tip}
  >
  > Set limits based on your capacity planning. Start conservative
  > and adjust based on metrics from `MyApp.Telemetry`.

  ## Examples

      iex> {:ok, limiter} = MyApp.RateLimiter.start_link(name: :api)
      iex> MyApp.RateLimiter.check(limiter, "user:42", :search)
      :allow

  ## Configuration

  | Key | Type | Default | Description |
  |-----|------|---------|-------------|
  | `:window_ms` | `pos_integer()` | `60_000` | Window duration |
  | `:max_requests` | `pos_integer()` | `100` | Requests per window |
  | `:ban_duration_ms` | `pos_integer()` | `300_000` | Ban duration after exceeding limit |

  ## Architecture

  <!-- tabs-open -->

  ### Single Node

  Uses a local ETS table. Suitable for development and single-instance
  deployments.

  ### Distributed

  Wraps the ETS table with `:pg`-based synchronization. Each node
  maintains its own counter and periodically reconciles with peers.

  <!-- tabs-close -->
  """
end
```
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall