Semi-private functions and documentation

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.

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.

+1 for Boundary and if you have a good module hierarchy going, you don’t even really need it (though probably better to have it on a team). When used in conjunction with @moduledoc false, parent module may always talk to their immediate children and siblings can talk to each other but only in one direction. It’s essentially a DAG (though sometimes you need to violate this like in schemas relationships).

If you have global modules like this, it’s trickier and Boundary will definitely help there.

Yeah, seems like that’s the path for packages and code that’s more public. (I’d probably still document the function in my own project with a standard disclaimer if I were writing a package.)

Too bad there’s just not a tag or attribute or something more official to deal with this.

I don’t even know that making the documentation private is the whole goal so much as making it clear that a particular function may be ephemeral, is subject to change, etc.

I worked on a function in Ash last night—the reason this conversation came to mine—and it didn’t have any documentation. I asked why and this was the reason, it is internal only but had to be public.

I added comments, but I’m not actually convinced excluding documentation is the best course, though having an option to only show stable APIs in the docs might be worth it? I just kinda thinking out loud here.

Boundary looks pretty interesting, but in my own case, it looks like overkill.

To me this seems like something that could at least be a candidate for something more official than “the core team has a current pattern.” Or maybe that’s fine. I guess I’m opening this topic to just get some ideas.

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.

I understand Erlang’s background and, as a former full time Rubyist, there was literally no real “private” functionality anyway. I actually prefer it that way. Maintainers cannot always anticipate the needs/ingenuity of their implementors.

I have copied private functionality in Phoenix because I needed it and couldn’t reuse it. I didn’t love it.

I have manipulated Ecto query structures directly because functionality I wanted was not available or even restricted. One can argue I shouldn’t have done that, but the fact is, it produced precisely what I wanted and still works fine two years later.

That aside this isn’t about me caring to restrict anything. A public function is a public function. This is more about a better, official way to communicate that sort of intent. Specifically communicating to implementors that an API is unstable/internal/not really meant to be used if you’re not working within the bounds of this hex package. This way things still get documented and that documentation might be just fine in the documents. If I use the full text search and come across something from a semi-private function that’s probably better than having that buried in comments.

Again, just a discussion from my end. Doing the above (just adding a standard disclaimer) has worked fine on my commercial/professional projects. I’d probably adopt the same pattern if I was maintaining a more public package.

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.

Of possible interest:

• Proposal: Private modules (general discussion)
• Proposal: Private modules (implementation specific) (closed)

Loooong dicussions, though.

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.