elixir-writing-docs

What This Skill Does

The elixir-writing-docs skill serves as an expert technical writing assistant specifically tailored for the Elixir programming language. It leverages the official ExDoc standards to ensure your module, function, and type documentation is consistent, discoverable, and readable. The skill provides architectural guidance on crafting effective @moduledoc, @doc, and @typedoc blocks, emphasizing the 'First-Line Summary Rule' to ensure documentation looks professional when rendered in ExDoc. It helps developers move beyond generic descriptions, guiding them to include essential sections like Examples, Configuration, and Behaviour callbacks while enforcing the use of proper Markdown syntax for cross-references and admonitions.

Installation

You can install this skill by running the following command in your terminal within the OpenClaw environment: clawhub install openclaw/skills/skills/anderskev/elixir-writing-docs

Use Cases

• Standardizing Documentation: Ensure all team members adhere to the same style guide for module documentation.
• Refactoring Legacy Code: Quickly generate high-quality docstrings for undocumented functions or modules.
• Writing Doctests: Convert ad-hoc examples into valid, testable iex> snippets that verify code functionality while documenting it.
• Onboarding: Help new developers understand how to document configuration requirements and behaviour expectations in Elixir projects.

Example Prompts

1. "Look at this module in lib/payment_processor.ex and improve the @moduledoc following the First-Line Summary Rule and adding an Examples section."
2. "I am defining a new behaviour for API clients. Can you suggest a template for the @moduledoc that includes a section for callbacks?"
3. "Review my @doc block for process_transaction/2. The current summary is too vague; rewrite it to be concise and indicate the return types."

Tips & Limitations

• Conciseness is Key: Always prioritize the first-line summary. If you find your summary spanning three lines, you are likely missing the core purpose of the unit.
• Doctest Limitations: While the skill provides templates, remember that doctests require the code to be compiled and accessible in the shell environment. Ensure your mix.exs dependencies are available.
• Formatting: Stick to standard Markdown headings. Avoid using # (H1) for section headers inside @moduledoc as ExDoc reserves this for the module name itself; use ## (H2) instead.
• Consistency: If you have multiple modules in the same project, use this skill to establish a common layout for configuration and error return types.