bug: elixier-analyzer is telling me to put @doc before @spec but I don't use @doc

[SethFalco]

I've just completed the Lucas Numbers exercise, but I'm getting automatic feedback with the following:

Developers can choose the order of the @doc and @spec modules attributes, but the Elixir community convention is to use @doc first and @spec next to the function.

However, I'm not even using @doc in my answer at all!

defmodule LucasNumbers do
  @moduledoc """
  Lucas numbers are an infinite sequence of numbers which build progressively
  which hold a strong correlation to the golden ratio (φ or ϕ)

  E.g.: 2, 1, 3, 4, 7, 11, 18, 29, ...
  """
  def generate(count) when not is_integer(count) or count < 1 do
    raise ArgumentError, "count must be specified as an integer >= 1"
  end

  def generate(1), do: [2]
  def generate(2), do: [2, 1]

  @spec generate(pos_integer()) :: [pos_integer()]
  def generate(count) do
    Stream.iterate({2, 1}, fn {x, y} -> {y, x + y} end)
    |> Enum.take(count)
    |> Enum.map(fn {x, _} -> x end)
  end
end

I also tried removing the @moduledoc to see if that would resolve it, but I still get the feedback. 🤔

[angelikatyborska]

Hi! I'm writing this as a guess, without testing, with the hope that you can test my thesis for me 🙏. I think the problem is that you put the @spec after 3 implementations of the function and before the 4th one. Could you move the @spec directly before the first implementation and see if that worked?

[SethFalco]

You're right!

This behaves as expected (no warning from elixir-analyzer):

defmodule LucasNumbers do
  @spec generate(pos_integer()) :: [pos_integer()]
  def generate(count) when not is_integer(count) or count < 1 do … end

  def generate(1), do: [2]
  def generate(2), do: [2, 1]

  def generate(count) do … end
end

But the following two have the warning reported in the original issue:

defmodule LucasNumbers do
  def generate(count) when not is_integer(count) or count < 1 do … end

  @spec generate(pos_integer()) :: [pos_integer()]
  def generate(1), do: [2]
  def generate(2), do: [2, 1]

  def generate(count) do … end
end

defmodule LucasNumbers do
  def generate(count) when not is_integer(count) or count < 1 do … end

  def generate(1), do: [2]
  def generate(2), do: [2, 1]

  @spec generate(pos_integer()) :: [pos_integer()]
  def generate(count) do … end
end

(All code snippets are truncated for brevity.)

[SethFalco]

I'm not sure if I'd be equipped to tackle this, but I peeked at the code and test cases.

I drafted the following test case:

test_exercise_analysis "no error when @spec is defined but not on the first clause of a multi-clause function",
  comments: [] do
  [
    defmodule Test do
      def sum(0, y), do: y
      def sum(x, 0), do: x
      @spec sum(number(), number()) :: number()
      def sum(x, y), do: x + y
    end
  ]
end

While working on this, I noticed there is a test that specifically asserts the opposite already though, so it seems the message raised by the issue is the intended behavior:

  test_exercise_analysis "@spec defined after function crashes",
    comments: [Constants.solution_function_annotation_order()] do
    [
      defmodule Test do
        def empty?(list) when list == [], do: true
        @spec empty?(list()) :: boolean()
        def empty?(_), do: false

- function_annotation_order_test.exs#L327

I do think the code and error message don't match, so there is a fix needed, but this could be split into 2 tasks? 🤔

• I think the function_annotation_order.ex should stop handling if the @spec came after the function clause.
• Then there should be a new generic rule that recommends @spec should always be before function clauses. And it sounds like that same rule might recommend @spec (and @doc?) is always written above the first definition of a multi-clause function?

I'm still learning Elixir and don't know all the conventions yet, so whatever you think is best!

PS: Feel free to call me a dummy if I'm saying something silly/wrong.

[angelikatyborska]

You're not saying anything wrong, no worries 🙂

While working on this, I noticed there is a test that specifically asserts the opposite already though, so it seems the message raised by the issue is the intended behavior:

Indeed. Given that the check's name is "function annotation order", the desired behavior was to do a single check for all the possible variations of @spec and @doc (those are the two function annotations). So it checks the order of @spec and @doc relative to one another, as well as the order of @spec relative to function definitions and the order of @doc relative to function definitions.

If we really wanted to extract those to more than one check, we would need three, given how I mentioned the three different aspects of the check 🙂. IMO that's a bit of an overkill.

I do think the code and error message don't match, so there is a fix needed

Indeed! Let's fix the message instead. I opened a PR: exercism/website-copy#2407