Yes, this is total non-sense. Our instance on docs and code comments have been clear since day one.

1. Documentation is for users of your code (who do not necessarily have access to source)
2. Code comments are for maintainers of the code (who are looking at the source right now)

It is really important to make this distinction because you often want to provide different information for those different “audiences”. Elixir makes use of both whenever necessary. Sometimes we even have a doc followed by extensive code comments. A user of the function does not care about implementation details but, if you are there in the source, trying to figure it out why it works like that, the information is there.

A private only exists in the source code, that’s why you can’t document something private. But you can certainly add code comments to it. Please do write code comments whenever you feel it is necessary.

The behaviour could be changed to discard @doc but I think allowing @doc in privates would open up a bunch of other problems. For example, if you try to write a doctest, it won’t work, because you can’t invoke a private function. Oh, do you want to access the @doc in your editor or terminal? That won’t work either, because private functions do not necessarily exist after the module is compiled, they can be inlined, transformed or even fully removed. Allowing @doc would indicate that those two constructs (public and private functions) are somewhat at the same level while they quite clearly aren’t.

All of this has already been said, so I will politely bow out of the discussion as I don’t have anything new to add here.

TL;DR:

defmodule Mod do
  @doc """
  Public docs
  """
  def public, do: ...

  # Private docs
  defp private, do: ...
end

that’s it!

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 @doc and @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 @doc?

Honestly, I never had a clue you could do this.

Just do this:

@doc """
This is a thing where I can write docs and stuff.
""" && false
defp my_very_long_function(arg) do
end