Feature to document

Compilation and Compiler API.

The Plugin API documentation is very good when it comes to the availability of hooks, but provides very little documentation of the Compilation and Compiler objects which are so heavily used in them - and the docs even say that

Among the two most important resources while developing plugins are the compiler and compilation objects. Understanding their roles is an important first step in extending the webpack engine.

There are some limited docs on the Compiler (which is not referenced from the plugin docs), but it does not cover most of the available methods or properties of the compiler. There doesn't appear to be even this much information on the Compilation, even though examples show some functionality (e.g. the "writing a plugin" section contains an example that writes to compilation.assets but there's no explanation of the assets property and how that works).

The issue template mentions a PR to the feature, but as it's a core part of webpack I'm not really sure what to reference!

Author(s)

@sokra, @TheLarkInn, and @ooflorent come up first in the contributors list for Compilation.js and Compiler.js but there are many contributors.

Additional information

While low level "this is what this method/property is and what it does" is useful, some sort of "if you're trying to do something like X, then try looking at Y method and Z property" might also be useful. I've ended up solving my particular problem (force a recompile of a given file whenever another given file changes) but in what I suspect is totally the wrong way - I figured out how to mess with the fileTimestamps entry for the file I wanted to force to recompiled, but I suspect that if I could somehow inform webpack of the dependency between the two then it would handle the rest itself.

[ ] I am willing to work on this issue and submit a pull request.

I cannot, because I don't understand them :D