In projects and libraries I’ve found that as things become more complicated, “semi-private” functions pop up. What do I mean by that? (I’m glad you asked.)
We all know and love private functions. I know I do. For me these functions do not have to support a stable API, can be gutted, changed, removed, or heck… even inlined by the compiler if necessary.
However, sometimes I need functionality that’s cross module but the function is something—especially in the case of creating a public library—that is considered private. “Hey, if you’re not working on this library, don’t use this function. It’s for internal use. Don’t rely on it. We might change it. Additionally, its functionality is really meant for the sorts of implementation details our consumers need not concern themselves with.”
The moment you want to use this cross module, it’s gotta be public. But there are some functions in a system you really care about a stable API and others that you don’t.
Even in my own commercial project where all the developers are working on the same codebase, there are pieces of functionality that are similar. “Don’t touch this unless working in conjunction with X. It’s exposed only because it has to be.” This works pretty well there.
Is there some official way to do a couple things:
Document a function but keep the documentation out of ExDoc? (Why would I want to do this? Because, like comments, you’d only see them in the codebase rather than in the docs.)
Mark a function as having an unstable API or unsuitable as an API? (This would be better, in my opinion.)
I’ve only seen two patterns that I took note of:
Document in comments only so the public docs show no docs. This works because only someone in the code sees the “docs” but it’s a bit jarring and I find it “ugly.”
Add a disclaimer to the docs for the function. “Don’t touch!” This is my preferred path, but if I were creating a library for a Hex package, I’d want something a bit more official.
WHAT I AM NOT ASKING: I’m not asking about whether semi-private functions are appropriate. I am not asking if I should reconsider their use. I’m asking if there is a better, official way to mark/handle/document said functions because they live in my codebase and the codebases of others.
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.
