That’s totally correct, but only for small projects which have always same team members. Bigger projects could share pretty simple API and do most of work in private functions. Also I would see some public functions as half-private i.e. available only for current library/project - something like dialyzer check for internal functions. Look how big changes could happen in some bigger companies. It could be really helpful if there would be a way to document internal part of projects which should be dedicated for future team members. Look that we still can’t move our minds to robots, so sooner or later everyone is going to be replaced by someone else. Current way of defining documentation could help people understand how to use specific library/project - not how it’s intended to work internally and not how it should be maintained in future.
For sure we can use comments like # TODO: description (of course really, really simple example) and create regular expressions in order to search for all places with such comment with shell commands like grep, but it’s not a solution which helps tooling Elixir. Libraries and projects like ex_doc can’t work directly on comments without extra tricks which are not needed for standard documentation. Such tricks does not allow to write simple tools enough quickly. Simply compare:
- depend on 3rd-party commands
- write extra code
- just fetch internal documentation by simple new switch in already existing API
I recommend to read:
https://forum.elixirforum.com/t/proposal-docp-for-private-function-documentation-and-doctests/3732?u=eiji
