Problems with documentation of modules that are Behaviours, `use`able and have own functions

Hello :slight_smile:

I have a small problem with elixir projects documentation. I constantly see a pattern where we have a module that has three meanings:

  1. it is a Behaviour which defines callbacks
  2. it has its own utility functions (some of them just take a module argument and call the callbacks)
  3. it has a __using__ macro that lets you use this module in your own module and have the callbacks automagically be implemented.

My problems with that are:

  1. Is there a reason why many callbacks do not have their own documentation? Or is it just an ommission? Also, should we document the callback or always add a function that takes a module argument and document it there? It feels weird to document the callback by saying what the “default implementation” does.
  2. The only place where some generated functions are documented is the moduledoc. Take the Phoenix.Presence.fetch/2 as an example ( ). It is mentioned in the moduledoc and guides but because of that I’m forced to read or look through the whole thing instead of quickly finding the function documentation. Some callbacks have their counterparts in functions taking a module argument, and have their own docs there (like list/1 and list/2 in the Presence module), but not all of them.
  3. Is this pattern documented anywhere in the Elixir guide? I see only . I feel like it deserves an elaboration.
  4. Often when looking at the module I see only the behaviour note and I’m not aware that I can use this module and it has the “default implementation”. I feel like we could expose that information, like with a use sign similar to the behaviour note on top. Or maybe we should always split the modules?

What is the best way to go about documenting such modules? When I use Phoenix I often just want to see what the automatically generated function does and sometimes I can’t do that easily without a lot of searching or reading the code. Also, I will be glad to contribute!


Ecto creates dummy modules for documentation purposes. There are a couple of places in phoenix that style would be useful too, maybe PR after seeing if they’d be interested in it?

1 Like

I feel like this pattern is so common we should have a way to document the default implementations inside of the __using__ macro…