Yes, this is total non-sense. Our instance on docs and code comments have been clear since day one.
- Documentation is for users of your code (who do not necessarily have access to source)
- Code comments are for maintainers of the code (who are looking at the source right now)
It is really important to make this distinction because you often want to provide different information for those different “audiences”. Elixir makes use of both whenever necessary. Sometimes we even have a doc followed by extensive code comments. A user of the function does not care about implementation details but, if you are there in the source, trying to figure it out why it works like that, the information is there.
A private only exists in the source code, that’s why you can’t document something private. But you can certainly add code comments to it. Please do write code comments whenever you feel it is necessary.
