How do I overload @doc strings?

Questions & Help Questions
,
1

I’m trying to work around the following warning:

warning: redefining @doc attribute previously set at line 78.

Please remove the duplicate docs. If instead you want to override a previously defined @doc, attach the @doc attribute to a function head (the function signature not followed by any do-block). For example:

    @doc """
    new docs
    """
    def get_futures_instruments(...)

I’ve tried to implement this advice, but can’t seem to work it out. What I’m doing is:

  @doc """
  Get all instruments, optionally filtered by underlying instrument(s)
  *** This is the main doc string that I'm trying to override below. ***
  """
  def get_futures_instruments(filter \\ nil)

  @doc "Get all instruments whose names start with the given `filter_str`"
  @spec get_futures_instruments(String.t() | nil) :: {:ok, list(map)} | error_response()
  def get_futures_instruments(filter_str) when is_binary(filter_str) or is_nil(filter_str) do
    ...
  end

  @doc "Get all instruments whose names start with any of those given in `filter_list`"
  @spec get_futures_instruments(list(String.t())) :: {:ok, list(map)} | error_response()
  def get_futures_instruments(filter_list) when is_list(filter_list) do
   ...
  end
2

I think what the warning is getting at, is that all your docs should be above

def get_futures_instruments(filter \\ nil)

Checking the docs for the docs (Writing Documentation — Elixir v1.12.3), it says:

  • Place documentation before the first clause of multi-clause functions. Documentation is always per function and arity and not per clause.

It seems like what you’re trying to do in the OP goes against this rule.

3

In what case then could I override a previously defined @doc? It doesn’t make sense to me to override a doc string by having two in a row.

4

Perhaps if a macro has written a @doc for you, then you might end up with two @doc.