Aid the reader in understanding the code

[jgonggrijp]

@jdittrich in #4290 (comment):

I wonder if code readability/learning/extending could be a focus in an update? That is not limited to code itself but also to documentation. It would not be a strong departure (though I find the event handling code difficult to understand sometimes) and might entail some potential compromizes where ease-of-understanding might be favored over performance, as well as architectural documentation (something between the line comments and the current documentation)

Me in #4290 (comment):

Could you elaborate a bit on how you would like to see this intermediate documentation?

@jdittrich in #4290 (comment):

intermediate documentation

…for me would usually involve

• What is already in "getting started"

• And then, for the larger code modules how to read and understand the respective code. For event handling (since that is the part that I know best) something like: What are the contracts/interfaces for an __Api-Function/Reducer, how is this._events structured, which "private" attributes are added to an object that uses the Events mixin (These are all focussed on the current way events work)

• JSDoc might help with the contracts/interfaces?

Basically, something that helps understanding how different parts of the code work together and how to read the code.

I suspect it would already help a lot if there were diagrams that visualize the relations between the different parts of the code. Those could be included right inside the Docco annotated source, because it supports Markdown inside the comments.

Comments welcome, as well as pull requests.