[erlang-questions] What I dislike about Erlang

[Loïc Hoguin]

On 08/31/2012 08:42 AM, Max Lapshin wrote:
> I really don't understand, what makes you sad.
>
> Is it that people don't write internal documentation? Perhaps it is
> because code is a documenation.

Only to an extent.

If your gen_server is only meant to be accessed through the API 
functions, then sure, that's fine.

If it can receive messages from other sources, then these should 
probably be documented. For gen_server the module description would be a 
good place to put explanations, and handle_info should probably have a 
detailed spec, clause by clause, on what it can receive.

I think the difficulty in documenting the protocol is that we write 
modules while the protocol is about processes. What do we do about 
processes that use more than one module that can send messages? I go 
about it with an "Internals" documentation but that's separate from the 
code.

-- 
Loïc Hoguin
Erlang Cowboy
Nine Nines
http://ninenines.eu