Warning, rant ahead.
I was trying to replicate asyncio Python functionality in D for a
script that needs some updating at work. I got inspired after
attending many talks and demos on the subject of async network
requests and disk IO at the PyOhio conference this past weekend.
I wanted to see if D was up to the task in part of my continuing
crusade to introduce D at my place of work. I just spent the last
five hours on this with no success and I give up; I'm just going
to rewrite the original script in Python3.
I tried writing the functionality in libasync[1] and the higher
level asynchronous[2] (not trying to pick on anyone, this is just
my experience). libasync has no online docs, which makes the
thing DOA for me. Regardless, I pushed on and got to the first
step with libasync's examples, but it didn't have some of the
higher level constructs that asyncio has, so I turned to
asynchronous, which seems to be a D port of Python's asyncio.
It has online documentation of all of the functions and classes,
great! But, the "examples" consist of the contrived tests and
don't show real usage. Imagine you just bought a piece of
furniture from Ikea, you have your toolbox and all of the parts
out, but someone forgot to include the instruction manual in the
box. You're smart enough to get the general shape of a dresser,
but it collapses under it's own weight because you really don't
know what you're doing. Or imagine trying to write a Java app in
a world where Design Patterns never existed. That's what working
with that kind of documentation is like. I can't for the life of
me figure out how any of these pieces fit together, so I'm
dropping it.
So please, if you don't want your hard work to go to waste, and
you want people to use your library, please put more effort into
better documentation. I love D, but I don't have the time to put
more trial and error into this. I could read the source of the
various libraries, I could continue banging my head against this
wall, I could write my own code from the ground up using just the
fiber interface. But at the end of the day, I need results, and
I've already spent too much time on this.
Things that make "good" documentation:
1. A description of the possible uses of the library, and what
you shouldn't use it for
2. The docs need to be accessible, that means having it online
and searchable.
3. Detailed descriptions of the parameter and return values
4. If something will throw, say what will throw and when
5. Descriptions of other ways you might be shooting yourself in
the foot. For example, documentation of alloca should warn about
what happens when the current stack frame is left
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.
A great example of good docs are the docs for
std.experimental.allocator[3]. It describes its goals, what it's
for, and how to practically use it in a program. Each function
has examples and parameter and return value descriptions.
[1]: https://github.com/etcimon/libasync
[2]: https://github.com/dcarp
[3]: https://dlang.org/phobos/std_experimental_allocator.html
