Explain the API in more details, adding rationale for design decisions

I also added the description of an unreleased feature, the default value
of events in publish()/subscribe().
Explain in more details and reformat documentation to clarify.

I introduced new examples and rewrote sentences where I felt that
clarifications were needed.

I replaced the first example using "score" with an example using "started"
in the continuation of previous examples.

I formatted 'this' as code when referring to the context object.
Describe new feature: 'this' refers to module data in listeners

Note: the feature is not implemented yet.
Replace 'example.tld' with 'example.org' in code samples

The .org extension is more familiar and less arcane than tld
(abbreviation of top-level domain).