Just to call out you can also do this:

defmodule Thing do

  @doc ""
  An explanation
  """ && false
  def semi_public(thing) do
  end
end

which will still exclude the doc from hexdocs but lets you write a doc still.

The most official way here is @doc false / @moduledoc false. The latter allows you to still have documentation for functions while having them not show up in ex_doc anyways. That’s the approach taken by elixir itself and you can see it used in many of the larger elixir projects like phoenix and others.

FWIW whenever I see @doc false / @moduledoc false in a library code, the intent is very clear to me and it is exactly what you describe.

This is a good point, not having these protected functions is a limitation that I also encounter very often.

For application code, I use boundary, it’s an extremely powerful concept to separate the internal functionality of a feature and create a public interface. I never tried to use a library that uses boundary, but I think it might work as well.

It doesn’t do any magic besides checking if you have boundary violations in your codebase, so it cannot make documentation private. I am not entirely sure, but I think you could disable documentation for unwanted modules by just doing @moduledoc false.

This is a tricky subject because it’s an open ended one. There’s a myriad of permutations around where, when and how a developer (or really some other piece of code) might be meant/allowed to use a function or not and for the former get more context (docs) or not.

Visibility from the language level (and really the runtime level) is nothing elixir can change. That comes with using erlang and the beam, which have visibility toggles on a per module level by either exporting or not exporting a function/type/….

The approach of using @moduledoc false is kinda an extension to the module level approach, where shared or extracted functionality, which is required to be publicly available, on the module is marked to not generate documentation to signify that functions on that module are not to be used by third party code. Boundary goes farther by enforcing such conventions at a technical level with a compiler as best as possible, but that requires spelling out the access patterns as well as types of “consumers of code” explicitly.

Both @doc false as well as Boundary can also do their signaling at a function level, where the former comes with the downside that you cannot have documentation and at the same time not have it.

None of these can prevent someone consuming the code as a dependency to ignore the signals and still call public functions even if not supposed to do that, given the beam simply doesn’t support that. The elixir compiler could attempt to statically check that, but things like apply and hot code updates mean that’ll never be perfect and Boundary already exists if you want to use an imperfect solution.