plymio_codi v0.3.1 Plymio.Codi.Pattern.Doc View Source

The doc pattern builds an @doc module attribute.

See Plymio.Codi for an overview and documentation terms.

Pattern: doc

Valid keys in the cpo are:

Key	Aliases
`:fun_name`	:name, :spec_name, :fun_name, :function_name
`:fun_args`	:args, :spec_args, :fun_args, :function_args
`:fun_arity`	:arity, :spec_arity, :fun_arity, :function_arity
`:fun_doc`	:doc, :function_doc

Examples

If the :fun_doc is false, documentation is turned off as expected:

iex> {:ok, {forms, _}} = [
...>   doc: [doc: false]
...> ] |> produce_codi
...> forms |> harnais_helper_show_forms!
["@doc(false)"]

The simplest :fun_doc is a string:

iex> {:ok, {forms, _}} = [
...>   doc: [doc: "This is the docstring for fun1"]
...> ] |> produce_codi
...> forms |> harnais_helper_show_forms!
["@doc(\"This is the docstring for fun1\")"]

For convenience, the :fun_doc can be :bang to generate a suitable docstring for a bang function. For this, the cpo must include the :fun_name, :fun_args or :fun_arity, and (optionally) :fun_module.

iex> {:ok, {forms, _}} = [
...>   doc: [name: :fun_one, arity: 1, doc: :bang]
...> ] |> produce_codi
...> forms |> harnais_helper_show_forms!
["@doc(\"Bang function for `fun_one/1`\")"]

iex> {:ok, {forms, _}} = [
...>   doc: [name: :fun_due, arity: 2, module: ModuleA, doc: :bang]
...> ] |> produce_codi
...> forms |> harnais_helper_show_forms!
["@doc(\"Bang function for `ModuleA.fun_due/2`\")"]

Similarly, :fun_doc can be :delegate to generate a suitable docstring for a delegation.

iex> {:ok, {forms, _}} = [
...>   doc: [name: :fun_due, arity: 2, doc: :delegate]
...> ] |> produce_codi
...> forms |> harnais_helper_show_forms!
["@doc(\"Delegated to `fun_due/2`\")"]

iex> {:ok, {forms, _}} = [
...>   doc: [name: :fun_due, arity: 2, module: ModuleA, doc: :delegate]
...> ] |> produce_codi
...> forms |> harnais_helper_show_forms!
["@doc(\"Delegated to `ModuleA.fun_due/2`\")"]