This a real strength for the Elixir world and something I wish was more common across development contexts. But it isn't perfect either.
The biggest weakness with ExDoc is oddly also one of it's greatest strengths: that the documentation is fairly tightly coupled with the code. Insofar as we're using the documentation as a reference for things like function explanations, this approach (unsurprisingly) works pretty well. But the way we structure our code across applications, modules, and functions for various technical or code quality reasons isn't the best way to build it's documentation.
For example, recently I've been learning the Phoenix Framework. For the framework to be both flexible and also so that the code is well organized, it's been coded across different Elixir projects: there's "phoenix", "phoenix_live_view", "phoenix_html", "phoenix_ecto", (etc). This division is absolutely appropriate, but it does mean that to do anything useful with the Phoenix Framework you're pretty certainly going to use a number of these different Elixir projects. But there's nowhere for the documentation to weave together the master plan of these different modules, the bigger ideas and concepts to exist. The most basic unit of documentation is the individual component and so when a real understanding how the components fit together is needed, there's no obvious place for that to live and often times you end up context switching between different sets of documentation.
Don't read this as ExDoc should account for this, but that it's easy to see ExDoc as the only documentation tool when often times complete documentation of complex projects requires something more.
This is partly the reason why we've built something custom for our documentation (using all of the wonderful tools provided by Elixir) at https://ash-hq.org. We still have a lot of work to do, but it allows us to provide a more wholistic documentation experience over all of our projects.
In all honesty, though, documentation is still a major hassle for people using the framework today. There is a lot to it, and even with a wholistic docs site it can often be hard to find what you want. But with this we at least have a singular vision to build towards, and its grown in leaps & bounds over the last 6-8 months.
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.
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.
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.
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.
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.
Is the long term intension to supplement tools like mix format and credo, or replace them? Would this project be accurated described as a combination of mix format and credo?
