[jayshua]

My only complaint is that I can't document defp functions. Yeah, they're not part of the public API. But in my non-library application the next developer coming along might need some info, and it would be nice to have it work the same way as all the other documentation.

[sbuttgereit]

I don't think your complaint is unreasonable, and I've even held that point of view in the past, but I can also see the other side of it.

A nice thing about ExDoc is that code documentation is placed in context alongside the code that is being documented. As others here have pointed out, you can, of course, still comment private functions using just plain old comments. The difference here is that ExDoc inline documentation will be published whereas the comments will not be. But if I really look at the use cases I don't see this as a real problem.

If I'm consuming, say, a library... at some level I don't/shouldn't care about the internals on a day-to-day basis where I'm principally using the documentation to understand the public API of the library. In fact, I might not look at the code of the library at all while still getting value out of both the library and it's published documentation. Anything more than the public API in the public documentation and I'm adding distractions which contextually aren't relevant... and in some sense shouldn't be relevant to my role as a client programmer.

For the developers where the situation is reversed, the developer that will maintain that same library, they'll want to have the documentation of the internals available. But I think much of the time if not most of the time, the inline documentation will be sufficient for that purpose. Since the maintenance developer will likely be working directly with the private function code at the time of need of documentation, the inline documentation via comments is likely where it is more useful compared to the published ExDoc documentation.

To be fair, there's a bit of rationalization here. But do think I've raised some fair points that might be behind the difference in thinking.

[jayshua]

Yes, that's basically the rational that Jose Valim (or was it someone else?) gives when asked. I still document almost every defp function in exactly the same way I document regular public functions though. (Why is it here, how should it be used, any gotchas to be aware of, etc.) It's just weird that I can't mark the exact same type of information using the same @doc syntax everywhere.

[di4na]

Then don't make them private?

I keep thinking that having depf was a mistake

[jayshua]

Idk, I think I still want them to be private. One example from just a few days ago was an ecto schema module that had a number of changesets. admin_changeset, director_changeset, manager_changeset, normal_changeset. Each one only differed from the others a bit, so the common code was factored into three or four helper functions that they each used as needed. Any of the *_changeset functions in the public API would always produce a working changeset, but the helpers could produce an broken changeset if not used correctly. (i.e., a changeset that would never successfully validate.) The helper functions are private to prevent misuse of the schema's api, but they also need to be clearly documented in basically the same way I would document the public functions. It just bothered me a bit that I couldn't use @doc for, quite literally, documentation.

[di4na]

Sure but then what you want is to mark them as "beware there are dragons" and move on.

[nesarkvechnep]

You can still document them, what’s stopping you?

[jayshua]

I can still document them with regular comments, just not with @doc documentation "comments" because the compiler gives a warning that @doc can't be used on private functions.

It just bothers me a bit that the stuff I'm putting in the comment is documentation that I would put inside a @doc on any non-private function, but I can't use @doc.