[erlang-questions] Erlang documentation -- a modest proposal
Richard A. O'Keefe
Fri Sep 23 07:30:31 CEST 2016
On 23/09/16 3:18 PM, Kenneth Lakin wrote:
> On 09/22/2016 05:55 PM, Loïc Hoguin wrote:
>> Examples are never a bad thing to have; at worst they provide no value
>> for the majority of people;
> If they make the documentation hard to read and understand, they're
> definitely a net negative.
I can only say that I have found the occasional example in the Unix
manual pages to be a lifesaver, and that the presence of examples in
the R documentation has often made it straightforward to use something
whose description was not particularly helpful. I suppose I can also
say that "show me a list of places where this method is called" has
been extremely informative when working on Smalltalk, even though those
aren't *crafted* examples.
Examples *instead* of documentation would be a bad thing.
Examples *mixed in with* documentation can be distracting.
So you have a library module.
- source code
Thanks to the magic of hypertext, these things don't have to be in the
same view. One reason for separating them is that somethings an
example *has* to be an example of several things, so it's nice that it
can be pointed to from several places, rather than duplicated.
More information about the erlang-questions