Hello 
I have a small problem with elixir projects documentation. I constantly see a pattern where we have a module that has three meanings:
- it is a Behaviour which defines callbacks
- it has its own utility functions (some of them just take a module argument and call the callbacks)
- it has a
__using__macro that lets youusethis module in your own module and have the callbacks automagically be implemented.
My problems with that are:
- 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.
- The only place where some generated functions are documented is the moduledoc. Take the Phoenix.Presence.fetch/2 as an example ( https://hexdocs.pm/phoenix/Phoenix.Presence.html#c:fetch/2 ). 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.
- Is this pattern documented anywhere in the Elixir guide? I see only https://elixir-lang.org/getting-started/alias-require-and-import.html#use . I feel like it deserves an elaboration.
- Often when looking at the module I see only the
behaviournote and I’m not aware that I canusethis module and it has the “default implementation”. I feel like we could expose that information, like with ausesign similar to thebehaviournote 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!
