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.
