docs: start rewriting docs

Author: hansl

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.

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",

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"
         }
       }

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 @@
       ]
     }
   }
-}
+}