[erlang-questions] Erlang documentation -- a modest proposal

[Loïc Hoguin]

On 09/23/2016 01:33 AM, Kenneth Lakin wrote:
> On 09/22/2016 02:56 PM, Lloyd R. Prentice wrote:
>> Fewer than half of the functions in the lists library,
>> for instance, have code examples. Suppose over the span
>> of one week we were collectively focus on generating at
>> least two code examples for each function in one library.
>
> Many of the functions in many of the libs are already sufficiently
> documented. Ferinstance, once one has read the explanatory prose for the
> relevant function, does one need code examples for lists:reverse/1 ?
> lists:sort/1 ? erlang:is_[binary|list|...]/1 ?

Yes. Someone with no experience will always appreciate them.

Not to mention that "sorted" in Erlang has a very specific meaning, 
which is not defined at all in the documentation for lists:sort/1.

Examples are never a bad thing to have; at worst they provide no value 
for the majority of people; at best they are easier to understand than 
the description.

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