Doctest with @typedoc

h-ikeda · May 24, 2020, 6:25am

ExUnit.DocTest.doctest/2 retrieves @moduledoc and @doc for functions, but does not @typedoc. Are there any way to test example codes in @typedoc ?

My function has many argument pattern like below:

def my_func({:a, options})
def my_func({:b, options})
def my_func({:c, options})

Then, I defines types:

@type a :: {:a, x: number}
@type b :: {:b, y: [number]}
@type c :: {:c, z: String.t}

Because this function will accept many type of arguments, I want to put example codes on @typedoc rather than @doc for my_func/1.

@typedoc """
Type explanation for a
    iex> my_func({:a, 5})
    [a: 5]
"""
@type a :: {:a, number}

@doc """
Simple function explanation
"""
def my_func({:a, options})

I expected code example in @typedoc is handled by DocTest, but it isn’t. It is maybe since doctest/2 treats docs from only functions and macros.

github.com

elixir-lang/elixir/blob/v1.10.3/lib/ex_unit/lib/ex_unit/doc_test.ex#L489


defp extract_from_moduledoc(annotation, %{"en" => doc}, module) do
  for test <- extract_tests(:erl_anno.line(annotation), doc, module) do
    normalize_test(test, :moduledoc)
  end
end

defp extract_from_docs(docs, module) do
  for doc <- docs, doc <- extract_from_doc(doc, module), do: doc
end

defp extract_from_doc({{kind, _, _}, _, _, doc, _}, _module)
     when kind not in [:function, :macro] or doc in [:none, :hidden],
     do: []

defp extract_from_doc({{_, name, arity}, annotation, _, %{"en" => doc}, _}, module) do
  line = :erl_anno.line(annotation)

  for test <- extract_tests(line, doc, module) do
    normalize_test(test, {name, arity})
  end
end

Is my approach against any conventions, or is there any way to test them?

josevalim · May 24, 2020, 7:42am

Please open up an issue and/or send a PR. I see no reason at the moment to not support it too.

h-ikeda · May 24, 2020, 8:03am

Sure, I will do soon. Thank you

After a while, I created a PR.