docs(angular): improve webpack-browser docs (#9461)

docs/generated/api-angular/executors/webpack-browser.md

@@ -1,14 +1,69 @@
 ---
-title: '@nrwl/angular:webpack-browser executor'
-description: 'Builds a browser application with support for incremental builds and custom webpack configuration.'
+title: "@nrwl/angular:webpack-browser executor"
+description: "The webpack-browser executor is very similar to the standard browser builder provided by the Angular Devkit. It allows you to build your Angular application to a build artifact that can be hosted online. There are some key differences:   
+- Supports Custom Webpack Configurations  
+- Supports Incremental Building"
 ---
 
 # @nrwl/angular:webpack-browser
 
-Builds a browser application with support for incremental builds and custom webpack configuration.
+The webpack-browser executor is very similar to the standard browser builder provided by the Angular Devkit. It allows you to build your Angular application to a build artifact that can be hosted online. There are some key differences:
+
+- Supports Custom Webpack Configurations
+- Supports Incremental Building
 
 Options can be configured in `workspace.json` when defining the executor, or when invoking it. Read more about how to configure targets and executors here: https://nx.dev/configuration/projectjson#targets.
 
+## Examples
+
+##### Using a custom webpack configuration
+
+The executor supports providing a path to a custom webpack configuration. This allows you to customize how your Angular application is built. It currently supports the following types of webpack configurations:
+
+- `object`
+- `Function`
+- `Promise<object|Function>`
+
+The executor will merge the provided configuration with the webpack configuration that Angular Devkit uses. The merge order is:
+
+- Angular Devkit Configuration
+- Provided Configuration
+
+To use a custom webpack configuration when building your Angular application, change the `build` target in your `project.json` to match the following:
+
+```ts
+"build": {
+    "executor": "@nrwl/angular:webpack-browser",
+    "options": {
+        ...
+        "customWebpackConfig": {
+          "path": "apps/appName/webpack.config.js"
+        }
+    }
+}
+```
+
+##### Incrementally Building your Application
+
+The executor supports incrementally building your Angular application by building the workspace libraries it depends on _(that have been marked as buildable)_ and then building your application using the built source of the libraries.
+
+This can improve build time as the building of the workspace libraries can be cached, meaning they only have to be rebuilt if they have changed.
+
+> Note: There may be some additional overhead in the linking of the built libraries' sources which may reduce the overall improvement in build time. Therefore this approach only benefits large applications and would likely have a negative impact on small and medium applications.  
+> You can read more about when to use incremental builds [here](/ci/incremental-builds#when-should-i-use-incremental-builds).
+
+To allow your Angular application to take advantage of incremental building, change the `build` target in your `project.json` to match the following:
+
+```ts
+"build": {
+    "executor": "@nrwl/angular:webpack-browser",
+    "options": {
+        ...
+        "buildLibsFromSource": false
+    }
+}
+```
+
 ## Options
 
 ### index (_**required**_)

packages/angular/docs/webpack-browser-examples.md

@@ -0,0 +1,47 @@
+##### Using a custom webpack configuration
+
+The executor supports providing a path to a custom webpack configuration. This allows you to customize how your Angular application is built. It currently supports the following types of webpack configurations:
+
+- `object`
+- `Function`
+- `Promise<object|Function>`
+
+The executor will merge the provided configuration with the webpack configuration that Angular Devkit uses. The merge order is:
+
+- Angular Devkit Configuration
+- Provided Configuration
+
+To use a custom webpack configuration when building your Angular application, change the `build` target in your `project.json` to match the following:
+
+```ts
+"build": {
+    "executor": "@nrwl/angular:webpack-browser",
+    "options": {
+        ...
+        "customWebpackConfig": {
+          "path": "apps/appName/webpack.config.js"
+        }
+    }
+}
+```
+
+##### Incrementally Building your Application
+
+The executor supports incrementally building your Angular application by building the workspace libraries it depends on _(that have been marked as buildable)_ and then building your application using the built source of the libraries.
+
+This can improve build time as the building of the workspace libraries can be cached, meaning they only have to be rebuilt if they have changed.
+
+> Note: There may be some additional overhead in the linking of the built libraries' sources which may reduce the overall improvement in build time. Therefore this approach only benefits large applications and would likely have a negative impact on small and medium applications.  
+> You can read more about when to use incremental builds [here](/ci/incremental-builds#when-should-i-use-incremental-builds).
+
+To allow your Angular application to take advantage of incremental building, change the `build` target in your `project.json` to match the following:
+
+```ts
+"build": {
+    "executor": "@nrwl/angular:webpack-browser",
+    "options": {
+        ...
+        "buildLibsFromSource": false
+    }
+}
+```

packages/angular/executors.json

@@ -18,7 +18,7 @@
     "webpack-browser": {
       "implementation": "./src/builders/webpack-browser/webpack-browser.impl",
       "schema": "./src/builders/webpack-browser/schema.json",
-      "description": "Builds a browser application with support for incremental builds and custom webpack configuration."
+      "description": "The webpack-browser executor is very similar to the standard browser builder provided by the Angular Devkit. It allows you to build your Angular application to a build artifact that can be hosted online. There are some key differences:   \n- Supports Custom Webpack Configurations  \n- Supports Incremental Building"
     },
     "webpack-server": {
       "implementation": "./src/builders/webpack-server/webpack-server.impl",
@@ -45,7 +45,7 @@
     "webpack-browser": {
       "implementation": "./src/builders/webpack-browser/webpack-browser.impl",
       "schema": "./src/builders/webpack-browser/schema.json",
-      "description": "Builds a browser application with support for incremental builds and custom webpack configuration."
+      "description": "The webpack-browser executor is very similar to the standard browser builder provided by the Angular Devkit. It allows you to build your Angular application to a build artifact that can be hosted online. There are some key differences:   \n- Supports Custom Webpack Configurations  \n- Supports Incremental Building"
     },
     "webpack-server": {
       "implementation": "./src/builders/webpack-server/webpack-server.impl",

packages/angular/src/builders/webpack-browser/schema.json

@@ -1,7 +1,8 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema",
-  "title": "Webpack browser schema for Build Facade.",
-  "description": "Browser target options",
+  "title": "Schema for Webpack Browser",
+  "description": "The webpack-browser executor is very similar to the standard browser builder provided by the Angular Devkit. It allows you to build your Angular application to a build artifact that can be hosted online. There are some key differences:   \n- Supports Custom Webpack Configurations  \n- Supports Incremental Building",
+  "examplesFile": "../../../docs/webpack-browser-examples.md",
   "type": "object",
   "properties": {
     "assets": {