For the Love of God, Please Write Better Docs!

[profan via Digitalmars-d]

On Tuesday, 2 August 2016 at 20:26:06 UTC, Jack Stouffer wrote:
> 6. Examples for every function. Simple examples are nice, but 
> an example which shows real world use is even better. You need 
> to show the user why this function exists.
> 7. Module level examples, meaning examples which show the 
> entire module working in tandem. For example, the standard 
> example for an async library is a async web crawler, which is a 
> great way to show how to do something basic in concept while 
> using a great number of features.

I can't agree more on the point of including examples of actual 
usage with your libraries, API docs in all their glory (which 
barely even exist for almost all D libraries in the wild as it 
is), examples help you actually understand how the pieces fit 
together.

It could be as simple as having an examples folder with sample 
projects in it, or like in std.experimental.allocator, embedding 
the example usage within the API documentation.

Either way, if anyone is interested in furthering D adoption, 
please include docs _and_ examples with your libraries.

(hey, my first post on the forums!)

Source code is not documentation.