Catching @doc deprecated: "..." annotations

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)

defmodule DemoModule do
  @on_definition ExampleCompiler

  @doc "hello"
  def hello() do

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

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

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

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

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


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

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


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


Thanks, very helpful link!