(Plugin) API Rewrite

[skipjack]

Work in progress...

This point of this pr is to:

• Resolve some longstanding API issues (see below).
• Standardize, simplify, and clarify various parts of the plugin API.
• Do some reformatting of the API section in general.
• Update and dedupe tapable docs.
• Bring the documentation up to date with the latest hooks available in v4.

Resolves #1505
Resolves #1458
Resolves #940

This also begins the process of resolving #1706. Notice that I've targeted this to a next branch where we can begin merging v4 related PRs. Once webpack v4 is fully released (around february it sounds like) we can...

• Tag master with the latest v3 version (e.g. 3.10.x) to make it easy to archive and make available later on.
• Rebase the next to make sure it's fully up to date with anything on master.
• Merge the next branch to master and continue improving the docs.

[skipjack]

@TheLarkInn @sokra I could really use some help with finishing the documentation on this branch soon (mostly just need to know the missing hook descriptions). I also think we need to update the following utility READMEs as such:

tapable

The updated docs were actually pretty solid and easy to follow. I think all that's missing is a description for each available hook.

enhanced-resolve

It seems the README for this package is totally out of date with the current code (though I could be wrong). I think the following needs to be documented:

• Each available hook (preferably using the same format we use here)
  • Type of underlying tapable hook
  • Brief description and optionally a small example
  • Any parameters passed
• A description of each available class method and their parameters (e.g. doResolve)

@mlcohen, seeing as you dug into this a bit in #1458, would you be willing to help out with updating the enhanced-resolve README? You may want to collaborate with @sokra and @TheLarkInn as I think the API changed a bit recently.

---

As for the documentation of both these utilities (tapable and enhanced-resolve) in this site, I'm tightening up the existing documentation in this pull request and linking out to each package for details. IMHO the public-facing APIs of those packages should be documented in only one place: their respective READMEs. The only thing that should be noted on this site is how the core of webpack uses their APIs internally. As I've mentioned elsewhere, once those READMEs are updated, we can pull them into a new "Utilities" section in this site (similar to Loaders and Plugins).

Trying to have this PR in a good place for review within the next 24 - 48 hours. Hoping we can then work together to knock this stuff out as this should solidify the API section of our site significantly and hopefully clarify a lot for our readers/users.

[TheLarkInn]

The updated docs were actually pretty solid and easy to follow. I think all that's missing is a description for each available hook.

So you mean this would be for authors looking to write their own hooks for their own plugin systems etc? @mlcohen could definitely help here.

[skipjack]

@TheLarkInn

So you mean this would be for authors looking to write their own hooks for their own plugin systems etc?

That too, but also for webpack plugin authors who just want to know how the SyncHook, SyncWaterfallHook, etc work and differ from one another. Something like...

SyncHook

Creates a hook that is executed synchronously... (etc.)

Methods: tap

...for each would be great. I know they may seem obvious to people who are very familiar with tapable or other similar systems but for new plugin authors (e.g. me) it's helpful to have some background. The "Methods" section could be left out I guess because I think it's made pretty clear later in the README that Sync*** hooks only allow tap and Async*** hooks allow all three.

I can move some of this to an issue in the tapable repo if that would help. Re @mlcohen, I was thinking they'd be able to help more with enhanced-resolve per the discussion in #1458 but if they have a good understanding of tapable as well that would be great. (this is all of course if @mlcohen has time 😜 ... no pressure)

[skipjack]

@TheLarkInn merging before this gets too far behind. I highly recommend that either you, @sokra, or someone else who is familiar with the webpack v4 hooks go through the following pages and fill out the hook descriptions:

• compiler-hooks.md
• compilation-hooks.md
• parser.md
• resolvers.md

I standardized the format of each hook section and I think I got all new/renamed hooks added. I didn't feel qualified enough to fill in the descriptions for the rest (i.e. every one with ...). I'm going to create issues on the tapable and enhanced-resolve repos to note what I mentioned above.