[erlang-questions] dialyzer output help
Mon Aug 10 14:47:27 CEST 2015
On 08/10/2015 02:33 PM, Garrett Smith wrote:
> I use edoc  to generate user docs for modules
I will argue that documentation generated from code isn't documentation.
After all, if everything is in the code, why not open the source file
directly, use powerful tools like 'git grep' for searching, and read the
source? You're guaranteed that the source is up to date, even if the
little comment above it isn't, and can avoid mistakes due to outdated
If you're going to write documentation, at least don't do it in a half
assed way. Make it an integral part of your project, not lousy comments.
Separate the documentation from the code. And respect the following
rule: *The documentation is always right*. If the code doesn't follow
the documentation, it's a bug, not the other way around.
Finally, for any large enough project you need three kinds of
documentation: a function reference (if it's a library), a user guide
and tutorials. The main reason you need all three is because different
people learn things in different ways.
(And yep, I still have to work on tutorials for my projects. This is
actually a recurring question from users who are actively seeking them
and have to rely on often outdated tutorials.)
Author of The Erlanger Playbook,
A book about software development using Erlang
More information about the erlang-questions