Thank’s everyone for their time on this. It is great to see that i think we have consensus on the need for this feature.
This was rejected as @kiko said on the pull request thread:
In this case, we have decided to reject EEP 67 on the basis that documentation attributes, introduced in OTP-27, is expressive enough to cover internal exports. Anything that has the documentation attribute
-doc false.or-doc hidden.does not produce the documentation and can be understood as an internal function.One can throw warnings using xref or using Dialyzer, by adding a new option that throws a warning when a hidden module is used externally.
However i must express my worry about decision making process in general and specifically surrounding documentation features that popped up here as well.
How can it be reasonable that we are supposed to express non documentation details with documentation parameters?
Sure there was practice in past to say “what is not documented should not be used” but is this really how we should think about this?
Internally exported is attribute regardless of documentation and if anything documentation should respect this attribute instead of expecting user to understand all the details and intricacies of documentation.
why are we starting to make decisions that are logically backward?
- let documentation attributes dictate visibility of functions instead visibility of functions dictating documentation profile
- introduce tool that is producing worse documentation and then hope it will be fixed instead of fixing the tool first and then introducing it (which i have alreade expressed here )
I’m calling once more for the OTP team to consider holistic approach of doing things and maybe step on the breaks a bit, because this has real potential of damaging erlang as a language especially for the new users (assuming we want new users).
Conversation with new user:
N: i want to export this for callback but i don’t want user to use it?
You: oh it’s easy just put -doc false or -doc hidden attribute
N: say what?
N: are you kidding me?
N: How was i supposed to search for that?
N: But i’n not currently even writing documentation
N: xref should be aware of documentation?
N: how many of these things are hidden in the language/ecosystem ?? (that i can not easily find)
This is insanity.