[erlang-questions] dialyzer output help

[Loïc Hoguin]

On 08/10/2015 03:04 PM, Roelof Wobben wrote:
> Op 10-8-2015 om 14:56 schreef Loïc Hoguin:
>> On 08/10/2015 02:51 PM, Garrett Smith wrote:
>>> On Mon, Aug 10, 2015 at 7:47 AM, Loïc Hoguin <essen@REDACTED> wrote:
>>>> Separate the documentation from the code
>>>
>>> For documenting modules along the lines of erlang.org's reference
>>> material [1] what do you do?
>>>
>>> [1] E.g. http://erlang.org/doc/man/lists.html
>>
>> This is what *they* do:
>>
>> https://github.com/erlang/otp/blob/maint/lib/stdlib/doc/src/lists.xml
>>
>> What I do is similar, except using Asciidoc:
>>
>> https://github.com/ninenines/gun/blob/master/doc/src/manual/gun.asciidoc
>>
>> (Tried a few formats over the years, settled on that one recently,
>> don't think I'll switch again. :-)
>>
>
>
> Thanks,
>
> 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.
>
> Roelof

I think for commenting code, Garretttt's advice was spot on. If you make 
the code readable on its own, mainly through the use of proper function 
and variable names, you don't need to put a comment above it to explain 
how it works.

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