Catching @doc deprecated: "..." annotations

Questions / Help
,
1

I am trying to hook into the @doc deprecated: "message" annotation using __on_definition__.

defmodule ExampleCompiler do
  def __on_definition__(env, _, fun, _, _, _) do
    doc = Module.get_attribute(env.module, :doc)
    IO.inspect(doc, label: fun)
  end
end

defmodule DemoModule do
  @on_definition ExampleCompiler

  @doc "hello"
  def hello() do
  end

  @doc deprecated: "hello2"
  def hello2() do
  end
end

Output of compilation:

hello: {11, "hello"}
hello2: nil

So, for some reason in the on_definition hook of the hello2 function, the module @doc attribute is empty whereas a keyword list [deprecated: ".."] would be expected. There seems to be something special in the compiler regarding the @doc module attribute, because when I change it to @doc2 it works as expected.

Also note the line number annotation in the first definition, this is also inconsistent with other module attributes. I have already been loking in the Module docs but I don’t see anything that tells me that @doc is special. Help appreciated :slight_smile:

1 Like
2

I assume that @doc just accepts a string and replaces anything else with nil.
Maybe you want hello2 looks like:

  @doc "hello2`
  @deprecated "use hello instead"
  def hello2() do
  end

I also assume that the line number means the position in the file not the position in the definition.

3

I would expect the keyword list approach to work because it’s also used this way in the stdlib. For example, from docs_test.exs:

@doc "Callback doc"
@doc since: "1.2.3", color: :red, deprecated: "use baz/2 instead"
@doc color: :blue, stable: true
@callback foo(any) :: any

and

@doc deprecated: "Use Logger.delete_process_level(pid) instead"
1 Like
4

Unfortunately it would be possible not sooner than in Elixir version 2.x, see: Provide an API to access documentation metadata at compile time · Issue #8095 · elixir-lang/elixir · GitHub

3 Likes
5

Yeah @doc deprecated: … is used for soft deprecation @deprecated is hard deprecation integrated with the compiler.

3 Likes
6

Thanks, very helpful link!