Not sure how to document defdelegate entries

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

@doc """
Split a comma-delimited string into a list of trimmed strings.
defdelegate str_list(in_str),       to: Strings

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


1 Like

Did you ever find an alternative?

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


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

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

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

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

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


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


sadly, no

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