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