<div dir="ltr"><div><div><div><div><div><div>i agree with  Lloyd .<br></div>i also spent countless hours when i was learning erlang  trying to understand some functions and how to use them .<br><br><br><blockquote style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex" class="gmail_quote">
So you have a library module.<br>
There are<br>
 - source code<br>
 - documentation<br>
 - examples<br></blockquote></div><br>source code can be even more confusing for a beginner as it may be written in  a very compact way that a beginner may not understand at that point in time although it may be crystal clear for others .<br></div>documentation does not contain examples for most functions so you are still stuck .<br></div><br></div>the maps module is one example of a module which would be very easy for a <b>newcomer</b> to use as all the functions have a short explanation followed by an example usage scenario .<br></div><br><div><div><div><div><div><div><div><div><br> <br><div><br></div></div></div></div></div></div></div></div></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Sep 23, 2016 at 5:30 AM, Richard A. O'Keefe <span dir="ltr"><<a href="mailto:ok@cs.otago.ac.nz" target="_blank">ok@cs.otago.ac.nz</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class=""><br>
<br>
On 23/09/16 3:18 PM, Kenneth Lakin wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
On 09/22/2016 05:55 PM, Loïc Hoguin wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Examples are never a bad thing to have; at worst they provide no value<br>
for the majority of people;<br>
</blockquote>
<br>
If they make the documentation hard to read and understand, they're<br>
definitely a net negative.<br>
</blockquote>
<br></span>
I can only say that I have found the occasional example in the Unix<br>
manual pages to be a lifesaver, and that the presence of examples in<br>
the R documentation has often made it straightforward to use something<br>
whose description was not particularly helpful.  I suppose I can also<br>
say that "show me a list of places where this method is called" has<br>
been extremely informative when working on Smalltalk, even though those<br>
aren't *crafted* examples.<br>
<br>
Examples *instead* of documentation would be a bad thing.<br>
Examples *mixed in with* documentation can be distracting.<br>
<br>
So you have a library module.<br>
There are<br>
 - source code<br>
 - documentation<br>
 - examples<br>
Thanks to the magic of hypertext, these things don't have to be in the<br>
same view.  One reason for separating them is that somethings an<br>
example *has* to be an example of several things, so it's nice that it<br>
can be pointed to from several places, rather than duplicated.<div class="HOEnZb"><div class="h5"><br>
<br>
______________________________<wbr>_________________<br>
erlang-questions mailing list<br>
<a href="mailto:erlang-questions@erlang.org" target="_blank">erlang-questions@erlang.org</a><br>
<a href="http://erlang.org/mailman/listinfo/erlang-questions" rel="noreferrer" target="_blank">http://erlang.org/mailman/list<wbr>info/erlang-questions</a><br>
</div></div></blockquote></div><br></div>