Well, I never said a word against writing inline comments here and there and I do that myself on a daily basis. This is like a stick-it note to future self, and this is fine.
I am advocating the clear split, in our mentality as well, between the documentation and drop-in comments.
I’m sorry to hear that this has been your experience. Mine have been the exact opposite, I have found that Elixir community has an emphasis on comprehensive documentation that I have rarely seen elsewhere.
I think this is the crux of it, it is (to me at least) strange that the comments I’m putting in my code are being used to generate the documentation. I expect a block of comments above my code to be used for myself or other developers working on it, if I then want to generate outside documenation for other people to consume - say if I’ve created a libary or whatnot - then I want to explicitly do that.
It is a mental shift that the comments in the code are expected to be used outside of the code as well. Still not sure how I feel about this, and I just ignore warnings for it when I document private functions 
Yes, this is total non-sense. Our instance on docs and code comments have been clear since day one.
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.
This explanation makes better sense than others I’ve seen so far.
I get this also, but it doesn’t satisfy my want for one consistent way to document/comment functions. In languages like C#, Java, Rust, Go, Crystal, etc. there’s one consistent way. The documentation creation tools for web pages and etc, just weeds out the private function docs.
We can try to use semantics to say comments aren’t documentation or documentation aren’t comments, but at the end of the day any character that’s written in source code, be it statements or comments, are documentation for someone.
Have enough people brought this topic up that it could at least be considered by the dev team?
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.
@doc comments are a qualitatively different thing from code comments. They document the API of a function. Code comments, document the how and why of the implementation. Wanting to use the same mechanism to perform two completely different tasks seems confused to me.
What about projects where these kind of users do not exist? My projects are mostly not libraries to be used by other people, rather, if there are other devs, they will have the source and may use the documentation to supplement that.
Issues to me that are caused by this enforcement of no @doc for private functions:
@doc that is used for that. It would be useful to see the description of a private function without scrolling.
