defmodule Mod do @doc """ Public docs """ def public, do: ... # Private docs defp private, do: ... end
While we can’t use
@doc for documenting private functions, nothing stops us for using comments to document them. Similarly, if a module is meant to be private we’d mark it as
@moduledoc false and document it by using comments. There are many such examples in Elixir itself and libraries.
I don’t think it’s fair to say that documenting internals is discouraged, it’s just we can’t use mechanisms like
@moduledoc for it.
@doc etc is used by the compiler to put documentation into beam chunks so that it can be later used by tooling like IEx, ExDoc etc to display public docs. Since private functions are, well, private, tools like IEx and ExDoc won’t seen them so it doesn’t make sense to use
@doc etc for them. In fact the compiler could even inline private functions as an optimisation. We could special-case
@doc not to put anything into beam chunk if it sees a private function, but that seems like needless complexity. Even if
@doc wouldn’t warn, since the tooling won’t show private docs, the only way to see them is to look at the source code. And at the source code, is it really a big deal to use a code comment over a