From 4493d885da3f94223f7afdcf97a86ad2eb8615d7 Mon Sep 17 00:00:00 2001
From: Hans <hans@hansl.ca>
Date: Fri, 5 Oct 2018 11:59:47 -0700
Subject: [PATCH] docs: start rewriting docs

---
 packages/angular/cli/commands/build-long.md         |  5 +++++
 packages/angular/cli/commands/build.json            |  4 ++--
 packages/angular/cli/commands/definitions.json      |  6 +++---
 .../build_angular/src/browser/schema.json           | 13 +++++++------
 4 files changed, 17 insertions(+), 11 deletions(-)
 create mode 100644 packages/angular/cli/commands/build-long.md

diff --git a/packages/angular/cli/commands/build-long.md b/packages/angular/cli/commands/build-long.md
new file mode 100644
index 0000000000..1116fcb1dc
--- /dev/null
+++ b/packages/angular/cli/commands/build-long.md
@@ -0,0 +1,5 @@
+Resources in CSS, such as images and fonts, are automatically written and fingerprinted at the root
+of the output folder.  If a resource is less than 10kb, it  is also included inline.
+
+Uses the Webpack build tool, with environment and build options specified in the CLI configuration
+file.
diff --git a/packages/angular/cli/commands/build.json b/packages/angular/cli/commands/build.json
index db73c39b06..043b370a99 100644
--- a/packages/angular/cli/commands/build.json
+++ b/packages/angular/cli/commands/build.json
@@ -1,8 +1,8 @@
 {
   "$schema": "http://json-schema.org/schema",
   "$id": "ng-cli://commands/build.json",
-  "description": "Builds your app and places it into the output path (dist/ by default).",
-  "$longDescription": "",
+  "description": "Compiles an Angular app into an output directory named dist/ at the given output path. Must be executed from within a workspace directory.",
+  "$longDescription": "./build-long.md",
 
   "$aliases": [ "b" ],
   "$scope": "in",
diff --git a/packages/angular/cli/commands/definitions.json b/packages/angular/cli/commands/definitions.json
index 201dd59e11..20099aaa74 100644
--- a/packages/angular/cli/commands/definitions.json
+++ b/packages/angular/cli/commands/definitions.json
@@ -7,21 +7,21 @@
       "properties": {
         "project": {
           "type": "string",
-          "description": "The name of the project to build.",
+          "description": "The name of the project to build. Can be an app or a library.",
           "$default": {
             "$source": "argv",
             "index": 0
           }
         },
         "configuration": {
-          "description": "Specify the configuration to use.",
+          "description": "A named configuration environment, as specified in the `configurations` section of `angular.json`.",
           "type": "string",
           "aliases": [
             "c"
           ]
         },
         "prod": {
-          "description": "Flag to set configuration to 'production'.",
+          "description": "When true, sets the build configuration to the production environment.\nAll builds make use of bundling and limited tree-shaking, A production build also runs limited dead code elimination using UglifyJS.",
           "type": "boolean"
         }
       }
diff --git a/packages/angular_devkit/build_angular/src/browser/schema.json b/packages/angular_devkit/build_angular/src/browser/schema.json
index c29931dee0..9a8cfd442b 100644
--- a/packages/angular_devkit/build_angular/src/browser/schema.json
+++ b/packages/angular_devkit/build_angular/src/browser/schema.json
@@ -12,15 +12,16 @@
     },
     "main": {
       "type": "string",
-      "description": "The name of the main entry-point file."
+      "description": "The full path for the main entry point to the app, relative to the current workspace.",
+      "$valueDescription": "fileName"
     },
     "polyfills": {
       "type": "string",
-      "description": "The name of the polyfills file."
+      "description": "The full path for the polyfills file, relative to the current workspace."
     },
     "tsConfig": {
       "type": "string",
-      "description": "The name of the TypeScript configuration file."
+      "description": "The full path for the TypeScript configuration file, relative to the current workspace."
     },
     "scripts": {
       "description": "Global scripts to be included in the build.",
@@ -55,7 +56,7 @@
     },
     "optimization": {
       "type": "boolean",
-      "description": "Enables optimization of the build output.",
+      "description": "When true, uses optimization for the app build.",
       "default": false
     },
     "fileReplacements": {
@@ -68,7 +69,7 @@
     },
     "outputPath": {
       "type": "string",
-      "description": "Path where output will be placed."
+      "description": "The full path for the new output directory, relative to the current workspace.\n\nBy default, writes output to a folder named dist/ in the current project."
     },
     "aot": {
       "type": "boolean",
@@ -408,4 +409,4 @@
       ]
     }
   }
-}
\ No newline at end of file
+}