docs(api): rewrite the parser documentation

Improve lead-in to give a little more context on what the parser does. Add
the latest hooks and use the same layout as the other pages in the section.

Author: skipjack

src/content/api/parser.md

@@ -4,92 +4,315 @@ group: Plugins
 sort: 4
 ---
 
-The parser instance takes a String and callback and will return an expression when there's a match.
+The `parser` instance, found in the `compiler`, is used to parse each module
+being processed by webpack. The `parser` is yet another webpack class that
+extends `tapable` and provides a variety of `tapable` hooks that can be used by
+plugin authors to customize the parsing process.
+
+The `parser` is found within [module factories]() and therefore takes little
+more work to access:
 
 ``` js
-compiler.parser.plugin("var rewire", function (expr) {
-    //if you original module has 'var rewire'
-    //you now have a handle on the expresssion object
-    return true;
-});
+compiler.hooks.normalModuleFactory.tap(factory => {
+  factory.hooks.parser.tap((parser, options) => {
+    parser.hooks.someHook.tap(...)
+  })
+})
 ```
 
+As with the `compiler`, `tapAsync` and `tapPromise` may also be available
+depending on the type of hook.
+
 
-## `program(ast)` bailing
+## Hooks
 
-General purpose plugin interface for the AST of a code fragment.
+The following lifecycle hooks are exposed by the `parser` and can be accessed
+as such:
 
 
-## `statement(statement: Statement)` bailing
+### evaluateTypeof
 
-General purpose plugin interface for the statements of the code fragment.
+`SyncBailHook`
 
+Evaluate the type of an identifier.
 
-## `call <identifier>(expr: Expression)` bailing
+Parameters: `expression`
 
-`abc(1)` => `call abc`
 
-`a.b.c(1)` => `call a.b.c`
+### evaluate
 
+`SyncBailHook`
 
-## `expression <identifier>(expr: Expression)` bailing
+Evaluate an expression.
 
-`abc` => `expression abc`
+Parameters: `expression`
 
-`a.b.c` => `expression a.b.c`
 
+### evaluateIdentifier
 
-## `expression ?:(expr: Expression)` bailing
+`SyncBailHook`
 
-`(abc ? 1 : 2)` => `expression ?!`
+Evaluate an identifier that is a free variable.
 
-Return a boolean value to omit parsing of the wrong path.
+Parameters: `expression`
 
 
-## `typeof <identifier>(expr: Expression)` bailing
+### evaluateDefinedIdentifier
 
-`typeof a.b.c` => `typeof a.b.c`
+`SyncBailHook`
 
+Evaluate an identifier that is a defined variable.
 
-## `statement if(statement: Statement)` bailing
+Parameters: `expression`
 
-`if(abc) {}` => `statement if`
 
-Return a boolean value to omit parsing of the wrong path.
+### evaluateCallExpressionMember
 
+`SyncBailHook`
 
-## `label <labelname>(statement: Statement)` bailing
+Evaluate a call to a member function of a successfully evaluated expression.
 
-`xyz: abc` => `label xyz`
+Parameters: `expression` `param`
 
 
-## `var <name>(statement: Statement)` bailing
+### statement
 
-`var abc, def` => `var abc` + `var def`
+`SyncBailHook`
 
-Return `false` to not add the variable to the known definitions.
+General purpose hook that is called when parsing statements in a code fragment.
 
+Parameters: `statement`
 
-## `evaluate <expression type>(expr: Expression)` bailing
 
-Evaluate an expression.
+### statementIf
 
+`SyncBailHook`
 
-## `evaluate typeof <identifier>(expr: Expression)` bailing
+...
 
-Evaluate the type of an identifier.
+Parameters: `statement`
 
 
-## `evaluate Identifier <identifier>(expr: Expression)` bailing
+### label
 
-Evaluate a identifier that is a free var.
+`SyncBailHook`
 
+...
 
-## `evaluate defined Identifier <identifier>(expr: Expression)` bailing
+Parameters: `statement`
 
-Evaluate a identifier that is a defined var.
 
+### import
 
-## `evaluate CallExpression .<property>(expr: Expression)` bailing
+`SyncBailHook`
 
-Evaluate a call to a member function of a successfully evaluated expression.
+...
+
+Parameters: `statement` `source`
+
+
+### importSpecifier
+
+`SyncBailHook`
+
+...
+
+Parameters: `statement` `source` `exportName` `identifierName`
+
+
+### export
+
+`SyncBailHook`
+
+...
+
+Parameters: `statement`
+
+
+### exportImport
+
+`SyncBailHook`
+
+...
+
+Parameters: `statement` `source`
+
+
+### exportDeclaration
+
+`SyncBailHook`
+
+...
+
+Parameters: `statement` `declaration`
+
+
+### exportExpression
+
+`SyncBailHook`
+
+...
+
+Parameters: `statement` `declaration`
+
+
+### exportSpecifier
+
+`SyncBailHook`
+
+...
+
+Parameters: `statement` `identifierName` `exportName` `index`
+
+
+### exportImportSpecifier
+
+`SyncBailHook`
+
+...
+
+Parameters: `statement` `source` `identifierName` `exportName` `index`
+
+
+### varDeclaration
+
+`SyncBailHook`
+
+...
+
+Parameters: `declaration`
+
+
+### varDeclarationLet
+
+`SyncBailHook`
+
+...
+
+Parameters: `declaration`
+
+
+### varDeclarationConst
+
+`SyncBailHook`
+
+...
+
+Parameters: `declaration`
+
+
+### varDeclarationVar
+
+`SyncBailHook`
+
+...
+
+Parameters: `declaration`
+
+
+### canRename
+
+`SyncBailHook`
+
+...
+
+Parameters: `initExpression`
+
+
+### rename
+
+`SyncBailHook`
+
+...
+
+Parameters: `initExpression`
+
+
+### assigned
+
+`SyncBailHook`
+
+...
+
+Parameters: `expression`
+
+
+### assign
+
+`SyncBailHook`
+
+...
+
+Parameters: `expression`
+
+
+### typeof
+
+`SyncBailHook`
+
+...
+
+Parameters: `expression`
+
+
+### call
+
+`SyncBailHook`
+
+...
+
+Parameters: `expression`
+
+
+### callAnyMember
+
+`SyncBailHook`
+
+...
+
+Parameters: `expression`
+
+
+### new
+
+`SyncBailHook`
+
+...
+
+Parameters: `expression`
+
+
+### expression
+
+`SyncBailHook`
+
+...
+
+Parameters: `expression`
+
+
+### expressionAnyMember
+
+`SyncBailHook`
+
+...
+
+Parameters: `expression`
+
+
+### expressionConditionalOperator
+
+`SyncBailHook`
+
+...
+
+Parameters: `expression`
+
+
+### program
+
+`SyncBailHook`
+
+Get access to the abstract syntax tree (AST) of a code fragment
+
+Parameters: `ast` `comments`