Basics
This check is disabled by default.
Learn how to enable it via .credo.exs.
This check has a base priority of normal and works with any version of Elixir.
Explanation
Every @doc string on a public function should include a ## Examples section.
Examples are the fastest way for a reader to understand what a function does.
Use iex> doctests for deterministic output; use a plain code block when the
result depends on runtime state.
# BAD — no Examples section
@doc """
Adds two numbers.
"""
def add(a, b), do: a + b
# GOOD
@doc """
Adds two numbers.
## Examples
iex> MyModule.add(1, 2)
3
"""
def add(a, b), do: a + bDefinitions listed in skip_def_types (macros, guards, private functions, and
delegates by default) are exempt from this requirement because they are less
amenable to illustrative iex> examples.
Check-Specific Parameters
Use the following parameters to configure this check:
:exclude_test_files
When true, skips test files. Default: false.
This parameter defaults to false.
:skip_def_types
Definition types that do not require a ## Examples section.
Defaults to [:defp, :defmacro, :defmacrop, :defguard, :defguardp, :defdelegate].
This parameter defaults to [:defp, :defmacro, :defmacrop, :defguard, :defguardp, :defdelegate].
General Parameters
Like with all checks, general params can be applied.
Parameters can be configured via the .credo.exs config file.