[erlang-questions] dialyzer output help

[Loïc Hoguin]

On 08/10/2015 02:33 PM, Garrett Smith wrote:
> I use edoc [1] 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 
comments.

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.)

-- 
Loïc Hoguin
http://ninenines.eu
Author of The Erlanger Playbook,
A book about software development using Erlang