Ex_doc: defdelegate to link docs

[coladarci]

We are making heavy use of defdelegate and it would be crazy helpful if the docs could somehow "crawl" that delegate so our code hinting could view the documentation of the delegated-to function.

For example:

If I have a function:

defmodule Bar do
  @doc """
  Options:
    - foo: pass true if you want to bar
  """
  def get_something(id, opts \\ []) do
  end
end

And I delegate to it:

defmodule Foo do
  defdelegate get_something(id), to: Bar
end

Then I call view the docs for Foo.get_something/1 (either the generated docs or w/ a code-hinting plugin), I don't have anyway of knowing the options I can pass in. My only option is to manually duplicate the docs, which is a shame.

Is there a convention for this that I'm not aware of?

Thanks!

[josevalim]

It was hard to do it before but now that we have documentation metadata we can do it. We first need to change Elixir to generate @doc delegate_to: {m, f, arity} and then we can leverage this from ExDoc. :+1:

[coladarci]

[gj]

I can take a crack at implementing this on the Elixir side. @josevalim, I'll look into the specific issue mentioned in this commit message, but do you remember any other pertinent details that may help me out?

[josevalim]

@gj that was an issue because we would always override the user provided documentation. With the metadata, there is no such issue. So we can always add @doc delegate_to: ..., read it in tools like ExDoc and automatically generate a documentation if one was not provided.

[gj]

@josevalim do you think the delegate_to: {M, F, A} documentation should be visible in IEx by default (like :deprecated or :since)?

[josevalim]

@gj that doesn't hurt either but let's do that as separate commits. :) Note that you can use Exception.format_mfa/3 to format the MFA. :)

[josevalim]

@gj your commit looks good, I have dropped a quick comment and we are ready to move forward.

[gj]

@josevalim updated code and tagged you on the new commit for comment 🎉

[PragTob]

:wave:

Do I understand the current state here correctly that we now have the elixir metadata to realize this and now we just need to pick it up in ExDoc and render it?

Also, am I seeing things or did this work some time in the past (I thought it did).

[josevalim]

@pragtob you are correct on both.

Before Elixir would add the default docs but that caused some limitations. So we had to remove the behaviour from Elixir and add it here.

[josevalim]

Fixed in 1ca9f028aee457b42ec2e0ae18e0cb7d8cb183ca.