feat(@angular/cli): add usage notes to help JSON

packages/angular/cli/models/interface.ts

@@ -112,6 +112,9 @@ export enum CommandType {
   Default = Custom,
 }
 
+/**
+ * A description of a command, its metadata.
+ */
 export interface CommandDescription {
   name: string;
   description: string;
@@ -119,7 +122,12 @@ export interface CommandDescription {
   /**
    * A long description of the option, in Markdown format.
    */
-  longDescription: string;
+  longDescription?: string;
+
+  /**
+   * Additional notes about usage of this command.
+   */
+  usageNotes?: string;
 
   options: Option[];
 

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

@@ -73,13 +73,29 @@ export async function parseJsonSchemaToCommandDescription(
     const ldPath = resolve(dirname(jsonPath), schema.$longDescription);
     longDescription = readFileSync(ldPath, 'utf-8');
   }
+  let usageNotes = '';
+  if (typeof schema.$usageNotes == 'string' && schema.$usageNotes) {
+    const unPath = resolve(dirname(jsonPath), schema.$usageNotes);
+    usageNotes = readFileSync(unPath, '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, longDescription, hidden, type, options, aliases, scope, impl };
+  return {
+    name,
+    description,
+    ...(longDescription ? { longDescription } : {}),
+    ...(usageNotes ? { usageNotes } : {}),
+    hidden,
+    type,
+    options,
+    aliases,
+    scope,
+    impl,
+  };
 }
 
 export async function parseJsonSchemaToOptions(