feat(@angular/cli): add long description and suboption option type

Author: hansl

packages/angular/cli/commands/add.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/schema",
   "$id": "ng-cli://commands/add.json",
   "description": "Add support for a library to your project.",
-  "$longDescription": "",
+  "$longDescription": "./add.md",
 
   "$scope": "in",
   "$impl": "./add-impl#AddCommand",

packages/angular/cli/commands/add.md

@@ -0,0 +1,2 @@
+Add support for a library in your project, for example adding `@angular/pwa` which would configure
+your project for PWA support.

packages/angular/cli/commands/generate-impl.ts

@@ -42,6 +42,12 @@ export class GenerateCommand<
 
       this.description.suboptions[`${collectionName}:${name}`] = options;
     }
+
+    this.description.options.forEach(option => {
+      if (option.name == 'schematic') {
+        option.type = 'suboption';
+      }
+    });
   }
 
   public async run(options: T) {
@@ -78,6 +84,7 @@ export class GenerateCommand<
   public async printHelp(options: T) {
     await super.printHelp(options);
 
+    this.logger.info('');
     if (Object.keys(this.description.suboptions || {}).length == 1) {
       this.logger.info(`\nTo see help for a schematic run:`);
       this.logger.info(terminal.cyan(`  ng generate <schematic> --help`));

packages/angular/cli/models/interface.ts

@@ -74,10 +74,17 @@ export enum OptionType {
  * An option description. This is exposed when using `ng --help-json`.
  */
 export interface Option {
+  /**
+   * The name of the option.
+   */
   name: string;
+
+  /**
+   * A short description of the option.
+   */
   description: string;
 
-  type: OptionType;
+  type: OptionType | 'suboption';
   types?: OptionType[];
 
   aliases: string[];
@@ -108,6 +115,12 @@ export enum CommandType {
 export interface CommandDescription {
   name: string;
   description: string;
+
+  /**
+   * A long description of the option, in Markdown format.
+   */
+  longDescription: string;
+
   options: Option[];
 
   aliases: string[];

packages/angular/cli/models/parser.ts

@@ -7,19 +7,21 @@
  *
  */
 import { strings } from '@angular-devkit/core';
-import { Arguments, Option, Value } from './interface';
+import { Arguments, Option, OptionType, Value } from './interface';
 
 
-function _coerceType(str: string | undefined, type: string, v?: Value): Value | undefined {
+function _coerceType(str: string | undefined, type: OptionType, v?: Value): Value | undefined {
   switch (type) {
     case 'any':
       if (Array.isArray(v)) {
         return v.concat(str || '');
       }
 
-      return _coerceType(str, 'boolean', v) !== undefined ? _coerceType(str, 'boolean', v)
-           : _coerceType(str, 'number', v) !== undefined ? _coerceType(str, 'number', v)
-           : _coerceType(str, 'string', v);
+      return _coerceType(str, OptionType.Boolean, v) !== undefined
+           ? _coerceType(str, OptionType.Boolean, v)
+           : _coerceType(str, OptionType.Number, v) !== undefined
+           ? _coerceType(str, OptionType.Number, v)
+           : _coerceType(str, OptionType.String, v);
 
     case 'string':
       return str || '';
@@ -56,7 +58,13 @@ function _coerceType(str: string | undefined, type: string, v?: Value): Value |
 }
 
 function _coerce(str: string | undefined, o: Option | null, v?: Value): Value | undefined {
-  return _coerceType(str, o ? o.type : 'any', v);
+  if (!o) {
+    return _coerceType(str, OptionType.Any, v);
+  } else if (o.type == 'suboption') {
+    return _coerceType(str, OptionType.String, v);
+  } else {
+    return _coerceType(str, o.type, v);
+  }
 }
 
 

packages/angular/cli/utilities/json-schema.ts

@@ -7,7 +7,8 @@
  */
 import { json } from '@angular-devkit/core';
 import { ExportStringRef } from '@angular-devkit/schematics/tools';
-import { dirname } from 'path';
+import { readFileSync } from 'fs';
+import { dirname, resolve } from 'path';
 import {
   CommandConstructor,
   CommandDescription,
@@ -57,12 +58,18 @@ export async function parseJsonSchemaToCommandDescription(
     });
   }
 
+  let longDescription = '';
+  if (typeof schema.$longDescription == 'string' && schema.$longDescription) {
+    const ldPath = resolve(dirname(jsonPath), schema.$longDescription);
+    longDescription = readFileSync(ldPath, 'utf-8');
+  }
+
   const scope = _getEnumFromValue(schema.$scope, CommandScope, CommandScope.Default);
   const type = _getEnumFromValue(schema.$type, CommandType, CommandType.Default);
   const description = '' + (schema.description === undefined ? '' : schema.description);
   const hidden = !!schema.$hidden;
 
-  return { name, description, hidden, type, options, aliases, scope, impl };
+  return { name, description, longDescription, hidden, type, options, aliases, scope, impl };
 }
 
 export async function parseJsonSchemaToOptions(