Expression.V2.Autodoc (expression v2.41.4)

Extract @expression_doc attributes from modules defining callbacks and automatically write doctests for those.

Also inserts an expression_docs() function which returns a list of all functions and their defined expression docs.

The format is:

@expression_doc doc: "Construct a date from year, month, and day integers",
                expression: "@date(year, month, day)",
                context: %{"year" => 2022, "month" => 1, "day" => 31},
                result: "2022-01-31T00:00:00Z"

Where:

  • doc is the explanatory text added to the doctest.
  • expression is the expression we want to test
  • fake_expression can optionally be the expression we want to display but not test
  • context is the context the expression is tested against
  • result is the result we're expecting to get and are asserting against
  • fake_result can be optionally supplied when the returning result varies depending on factors we do not control, like for now() for example. When this is used, the ExDoc tests are faked and won't actually test anything so use sparingly.

Summary

Functions

annotate_method(module, function, args)

format_context(context)

format_docs(docs)

format_function_args(args)

format_function_name(name)

format_result(result)

generate_assert(prompt, result)

generate_ex_doc(prompt \\ "iex", module, expression, context, result)

get_existing_docstring(module)

get_expression(expression_doc)

stringify(value)

type_of(boolean)

update_annotations(module, function, args, expression_docs)