API - Clarify Plugins Structure and Flow

[aight8]

The page especially missing:

1. Description of all class instance properties

2. A flow of the plugins - a) where you can hook and where it is in the flow b) when webpack do what internally. I found this chinese website which go the direction I mean: https://github.com/liangklfangl/webpack-compiler-and-compilation

3. This is difficult to understand:

Plugin Interfaces
There are two types of plugin interfaces.

Timing based

sync (default): As seen above. Use return.
async: Last parameter is a callback. Signature: function(err, result)
parallel: The handlers are invoked parallel (async).

Return value

not bailing (default): No return value.
bailing: The handlers are invoked in order until one handler returns something.
parallel bailing: The handlers are invoked in parallel (async). The first returned value (by order) is significant.
waterfall: Each handler gets the result value of the last handler as an argument.

4. Show ES6 class variant of the plugin architecture beside the prototyped one (encourage plugin developer to use classes)

5. Explain entirely what seal means in webpack

6. compilation(c: Compilation, params: Object)

A Compilation is created. A plugin can use this to obtain a reference to the Compilation object. The params object contains useful references

I LOVE useful references. But what kind of?

[skipjack]

@TheLarkInn can you take a look at this and tell us what you think? I think 2 - 6 are more clarification and tweaking the existing doc whereas 1 might be a new page or bigger update.

[skipjack]

This is partially resolved by the rewrite of this section I did on the next branch (#1754) and should be fully resolved once webpack/tapable#48 is addressed. I recommend taking a look at the next branch and submitting more targeted PRs or issues for anything else that you think can be improved.