[erlang-questions] dialyzer output help

Richard A. O'Keefe ok@REDACTED
Tue Aug 11 05:26:55 CEST 2015


On 11/08/2015, at 1:04 am, Roelof Wobben <r.wobben@REDACTED> wrote:
> 
> But now I more confused.
> Im reading the introducing erlang book and there is always stated to document your code.
> 
> I find this the most difficult part because how do I document something like the area function.

Documentation is EXPLAINING STUFF TO PEOPLE.

How do you document the area function?
Imagine someone coming along who knows enough about
Erlang to call your function.
WHAT DO THEY NEED TO KNOW ABOUT IT?

If they have access to the source code,
you ask a slightly different question:
WHAT DO THEY NEED TO KNOW ABOUT IT THAT
IS NOT OBVIOUS IN THE CODE?

Nobody can give you precise programming-language-oriented
rules about documentation because documentation is mainly
about PEOPLE, not programs.

The code tells people what DOES happen.
The documentation tells people what SHOULD happen,
WHY it should happen, and a few other things.

You got one part of your documentation BRILLIANTLY RIGHT,
either in this thread or another, where you said
what the exercise was you were trying to solve.
Honestly, that was by a very large factor the most useful
comment you had.




More information about the erlang-questions mailing list