Not sure how to document defdelegate entries

Questions / Help
, ,
1

Dave Thomas suggests that folks put the interface definition for a component into lib/foo.ex, then put all the implementation code into lib/foo/*.ex. I’ve been using this approach and like it a lot, but I’m not sure how to document the defdelegate entries.

Although I could put all of the interface documentation into lib/foo.ex, this would defeat much of the purpose of using lib/foo/*.ex. The @doc entries would be separated from the code and the lib/foo.ex file would become awkwardly large.

So, I’ve been using placeholder @moduledoc and @doc entries in lib/foo.ex, containing links to the “real” documentation, as follows:

@moduledoc """
This module defines the external API for the Common component.
Each "function" actually delegates to a public function in
`common/*.ex`.
"""

@doc """
Split a comma-delimited string into a list of trimmed strings.
([`...Strings.str_list/1`](Common.Strings.html#str_list/1))
"""
defdelegate str_list(in_str),       to: Strings

However, this seems a bit tedious. Am I missing an easier WTDI?

-r

1 Like
2

Did you ever find an alternative?

3

There is a metadata available in ExDoc for this (and well hidden too…)

@doc delegate_to: {M, F, A}

that will print See M.F/A

Example:
Considering:

defmodule DelegateDoc.Sub do
  @doc """
  This is my delegated func doc
  """
  def my_delegate(_arg) do
    # do stuff
  end
end

defmodule DelegateDoc do
  @moduledoc """
  Documentation for DelegateDoc.
  """

  @doc deletegate_to: {DelegateDoc.Sub, :my_func, 1}
  defdelegate my_delegate(arg), to: DelegateDoc.Sub
end

will end up like this in docs:
delegate_doc_exmple
Sorry I don’t know how to embed images…

And @doc deletegate_to: &DelegateDoc.Sub.my_func/1 will work too

3 Likes
4

Yes! Note this metadata is automatically set by defdelegate too.

3 Likes
5

sadly, no

6

I couldn’t get this to work:

@doc delegate_to: &DelegateDoc.Sub.my_func/1

but the first format seems to work fine.

1 Like