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:

1. 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.)
2. 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:

1. 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.”
2. 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.