Recode: An experimental Elixir linter with autocorrection and refactoring tools
github.com
github.com
I keep thinking that having depf was a mistake
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.
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.
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.
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.
Nevertheless, very excited. I miss ReSharper dearly from my C# days and this will be great.