Is it necessary to warn about the @doc attribute for a private function

And which of those language make a distinction between documentation and code comments? Otherwise they do not provide the distinction which is the root reason of this conversation and therefore I don’t believe it is an apt comparison.

The other language I know that provides a similar distinction to Elixir, which is Python, recommends in its official style guide to use comments for privates:

Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does. This comment should appear after the “def” line.

You just said my explanation makes better sense than all others, then why not give it a try? The first step then is to recognize that not all characters in the source code are documentation. To clarify, I understood what you meant, but because we are talking about semantics, then terminology matters.

Try to adopt the new terminology and then in the future you can write down your first hand experiences, what worked and what didn’t.

The other thing I have remembered is that documentation and comments are different contracts too. A documentation is a contract beyond the current source file. A code comment is tied to the current source. There is really a lot you can learn and express by separating those two concerns.

A lot of people asked for a JSON library in core and that is not happening. A lot of people asked for variations of the pipe operator and that is not happening either. Features are not driven by how many people ask for it. :slight_smile:

7 Likes