I have the same feeling about the warning, maybe not even using a new attribute like docp. If that warning is to warn you that you are documenting a function that will never used outside and maybe you declared it wrong by using defp instead of def then the undefined function check will catch it. Or if the documentation will not render on hexdocs it’s ok too it’s private the function will not appear there anyway. Just let us write our docs

Sure thing. What you are missing is the main point: if there is a need to document a private function, it means there is a need for other developers to use this private function, which means it should not be private.

Private functions are not meant to be re-used. Private functions might stay there forever, but they are just implementation details, they are none of anybody’s business.

If you find yourself explaining to mates what your private functions do, you are either teaching them Elixir in general, or doing it plain wrong.

Yeah sure, I get some of what you say, but I don’t think you’re thinking about every situation where you might want to document something you’re doing. Let’s say for instance you’re interfacing with someone else’s api which may be a little complicated, or maybe not. You may want to document why, or what the api is requiring from you in that function.

Or even better, this is a dynamic language, and not everyone uses dialyzer. You may want to document the format of the returned data.

Maybe i’m trying to conform to an RFC and I want to document where to find it.

There are plenty of reasons why I want to document something. All these “you’re doing it wrong if you have to document it” excuses is really just a blow off answer.

To directly answer your “it means there is a need for other developers to use this private function”, that’s not the only case. It’s possible that my logic is completely wrong, or something breaks later on down the road. I want to let the developer that comes after me know why I chose to do something the way I did, or what I thought my function was going to do/return.

I haven’t been programming for that long, but I swear I’ve never seen a community so against documenting their code or making others feel like dog crap for wanting to document theirs.

I never ever meant this. What I meant is being restrictive here, Elixir compiler plays the role of linter. There are 100 to 1 cases when documenting private functions is wrong. For the rest one still has any other type of comment, including but not limited to assigning the module attribute like

@future_readers """
This is implementing that, it’s done that way because of this. Thanks for understanding.
"""

Allowing comments for privates because not everyone uses dialyzer is exactly what we are against of. It’s like allowing "0" == 0 because not everyone uses proper type conversions, IMSO.

This is kind of what I’m talking about “what we are against”. We who? The coding gods that say “Thou shalt program the way I want you to program?”

And, if the coding gods want us to always use Dialyzer, something that’s not even a part of the language, then the coding gods should make the language strongly typed.

I don’t buy this at all. If you’re writing code that is going to be pushed into production, and you’re not commenting it, you’re treating the people that are going to have to debug the code later just plain wrong.

It doesn’t matter that anyone here thinks that you shouldn’t write a private function, or whatever the case is. People are going to write code, and they’re probably going to write it in a way that you think they shouldn’t. It doesn’t matter. There still should be a standard way of documenting or commenting it. The way for that was chosen… @doc. That should be available everywhere.

That is where you got it wrong. The way for that was chosen (by language creator.) This way is (like it, or hate it, it does not actually matter): you use @doc to comment public functions only, period.

There is nothing more overhyped for zero value than strong typing. It brings literally nothing save for headaches and enormously huge boilerplates.

This is the whole reason for this post. The fact that it can only be used for public functions. In my opinion, and obviously others since there are more posts on this forum talking about it, that it should be open to all functions, not just public.

That’s an opinion, and you already went against it when you suggested that commenting be replaced by using dialyzer, which is a typing addon to the language.

I think the ‘problem’ is that there isn’t a way to just comment and document (in the ‘what this does’ sense, not the ‘create documentation’ sense) a function no matter what it is.

@doc is used to also create documenation automatically - hence people saying don’t use it for private functions, as you don’t want other people to consume those really.

What you want is something like a @nodoc or @docno that allows you to use the same format to comment code, but without it getting attached to auto generatred docs?