I quite often put the API for a library in the top-level module, but delegate all the calls down into various implementation modules.
This leaves we with the problem of where to put the @doc. I want to put it in the API module so that clients of the library can see all the API documentation by asking for help on the functions they actually call. I also want to put it in the implementation modules so that people reading the code have access to it. So, my suggestion: if a defdelegate does not have its own documentation, could it receive a copy of the documentation of the function it delegates to? This means the source could have just one copy (in the implementation), but iex, hexdocs etc would also see it at the top level. This would be my preferred change. However, if it isn’t acceptable, I have a plan B. Could we have an @see directive which could be used with @doc and @moduledoc ? @doc @see Mylib.Stats.stddev defdelegate stddev(sample), to: Mylib.Stats If @see is passed a module, it returns the moduledoc. If passed a function name, it returns the docstring. If passed a string, it returns the contents of the given file. Whaa??? you say. Doing this means we can document the top-level using @moduledoc @see "README.md" -- You received this message because you are subscribed to the Google Groups "elixir-lang-core" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/d94f489a-74cc-4f79-9c77-d13a06d68123%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
