The problem with @moduledoc false is, that one not only needs to see it, but also needs to understand it.
Does the one who calls into that module even know the difference (which only is by convention) between no @moduledoc/@doc at all and @moduledoc false/@doc false?
I’ve a few other examples as well:
Afaik @kip was aware he was using private API, but the issue is that there’s no proper incentive to speak to the maintainer to make it public vs. just using the private api as is – at least not yet. Private API in elixir (e.g. mix) is especially problematic because of the rather fixed release cycle. The goal of this proposal is to my understanding to force (or at least promote) the work/discussion of such cases to happen at an earlier stage – at the place where someone want’s to use a private api opposed to when the dependency (elixir, plug, ecto, …) finally updates and breaks things.
Even if the private API could just be made public a few month down the line a package could at least depend on the exact version, where it’s still private, call the private API and make a note to release a new version using any updated public API when it’s released. Anybody updating before the new release would get a warning that the package does not work with e.g. elixir 1.X yet. Not perfect, as the private API could still break before the next release, but at least both parties are aware of the issues and when it’s to be properly resolved.
It looks like for the absinthe case, it was more complex than just using a private API
https://github.com/absinthe-graphql/absinthe/commit/96058883c8a67382c0eea41a464136318d9f9717
We work on a biggish Elixir app and this is something we spent few hours discussing, I believe that private modules is a must have and lean towards option D and C.
I don’t mind would be that error or a warning as we are able to return error on warnings (and we do it already), but with option D debugging would be harder, because you need to know that your function is magically lives in another module :"Elixirp.Foo.Bar".
Also, are private modules going to be accessible from tests unlike private functions? A private module can contain a lot of functionality and testing all edge cases in a high-level function that calls a private module would lead to code duplication and increased complexity. So I beleive we should test it as any other module.
One other thing I’m not sure is listing each caller module individually, namespacing looks more practical here - I would like to allow all modules in current domain context to call private module. But I’m not sure it’s possible to implement it this way because we don’t know all the modules within a context beforehand.
@sasajuric How does this mesh with what you said in your book that module name nesting is just syntactic sugar and doesn’t imply any special relationship between modules.
This proposal seems like it will trigger special relations between nested modules. Curious what your thoughts are.
The . character is just another character in the module name, so the runtime doesn’t care about it at all. Of course, the tooling can introduce additional rules and conventions (if I’m not mistaken, this is already done with protocols).
It doesn’t look like the proposal A introduces any special relationship based on the . character (or any other character), but it does introduce a special relationship based on the module attribute (@module_visible_to, or however it’s going to be called).
I personally like this proposal, since I was never really convinced that @moduledoc false is sufficient. This proposal looks lightweight, and it should help with a better communication of intent and make things more enforceable.
Folks, I will go ahead and close the thread, as it has reached its natural course. Of course, new discussions around the topic are welcome and can link back to it. Thanks!