Merge pull request #3 from forcedotcom/td/update

Fix multiline description

.prettierignore

@@ -0,0 +1 @@
+/templates

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "editor.formatOnSave": false
+}

src/ditamap/command.ts

@@ -7,45 +7,42 @@
 
 import { asString, Dictionary, ensureJsonMap, ensureObject, ensureString, JsonMap } from '@salesforce/ts-types';
 import { join } from 'path';
-import { punctuate } from '../utils';
+import { helpFromDescription, punctuate } from '../utils';
 import { Ditamap } from './ditamap';
 
+export type CommandHelpInfo = {
+  hidden: boolean;
+  description: string;
+  longDescription: string;
+  required: boolean;
+  kind: string;
+  type: string;
+};
+
 export class Command extends Ditamap {
   constructor(topic: string, subtopic: string, command: Dictionary, commandMeta: JsonMap = {}) {
     const commandWithUnderscores = ensureString(command.id).replace(/:/g, '_');
     const filename = `cli_reference_${commandWithUnderscores}.xml`;
 
-    const flags = ensureObject(command.flags);
-
     super(filename, {});
 
-    const parameters = Object.entries(flags)
-      .filter(([, flag]) => !flag.hidden)
-      .map(([flagName, flag]) => {
-        if (!flag.longDescription) {
-          flag.longDescription = punctuate(flag.description);
-        }
-        return Object.assign(flag, {
-          name: flagName,
-          longDescriptionPs: this.formatParagraphs(flag.longDescription),
-          optional: !flag.required,
-          kind: flag.kind || flag.type,
-          hasValue: flag.type !== 'boolean'
-        });
-      });
+    const flags = ensureObject(command.flags);
+    const parameters = this.getParametersForTemplate(flags as Dictionary<CommandHelpInfo>);
 
+    // The template only expects a oneline description. Punctuate the first line of either the lingDescription or description.
+    const description = punctuate(asString(command.longDescription) || asString(command.description));
+    // Help are all the lines after the first line in the description. Before oclif, there was a 'help' property so continue to
+    // support that.
+    const help = this.formatParagraphs(asString(command.help) || helpFromDescription(asString(command.description)));
     let trailblazerCommunityUrl;
     let trailblazerCommunityName;
+
     if (commandMeta.trailblazerCommunityLink) {
       const community = ensureJsonMap(commandMeta.trailblazerCommunityLink);
       trailblazerCommunityUrl = community.url;
       trailblazerCommunityName = community.name;
     }
 
-    if (!command.longDescription) {
-      command.longDescription = punctuate(asString(command.description));
-    }
-
     let fullName: string;
     if (subtopic) {
       fullName = commandWithUnderscores.replace(`${topic}_${subtopic}_`, '');
@@ -57,8 +54,8 @@ export class Command extends Ditamap {
       binary: 'sfdx',
       // The old style didn't have the topic or subtopic in the reference ID.
       full_name_with_underscores: fullName,
-      helpPs: this.formatParagraphs(asString(command.help)),
-      longDescriptionPs: this.formatParagraphs(asString(command.longDescription)),
+      help,
+      description,
       parameters,
       isClosedPilotCommand: state === 'closedPilot',
       isOpenPilotCommand: state === 'openPilot',
@@ -75,6 +72,24 @@ export class Command extends Ditamap {
     }
   }
 
+  public getParametersForTemplate(flags: Dictionary<CommandHelpInfo>) {
+    Object.entries(flags)
+      .filter(([, flag]) => !flag.hidden)
+      .map(([flagName, flag]) => {
+        const description = this.formatParagraphs(flag.longDescription || punctuate(flag.description));
+        if (!flag.longDescription) {
+          flag.longDescription = punctuate(flag.description);
+        }
+        return Object.assign(flag, {
+          name: flagName,
+          description,
+          optional: !flag.required,
+          kind: flag.kind || flag.type,
+          hasValue: flag.type !== 'boolean'
+        });
+      });
+  }
+
   public getTemplateFileName(): string {
     return 'command.hbs';
   }

src/utils.ts

@@ -43,5 +43,14 @@ export function punctuate(description: string): string {
   if (mainDescription.charAt(mainDescription.length - 1) !== '.') {
     mainDescription += '.';
   }
-  return [mainDescription, ...lines.slice(1)].join(EOL);
+
+  return mainDescription;
+}
+
+export function helpFromDescription(description: string): string {
+  return description
+    .split(EOL)
+    .slice(1)
+    .join(EOL)
+    .trim();
 }

templates/command.hbs

@@ -10,7 +10,7 @@ IF YOU WANT TO CHANGE THIS CONTENT, CONTACT rsears@salesforce.com FOR DETAILS.
 -->
     {{!--Not all commands have a minor noun; some are just commandmajornoun:commandverb. This is a sample topic for a commmand with no minor noun.--}}
     <title><ph id="topic-title"><codeph otherprops="nolang">{{id}}</codeph>{{#if isClosedPilotCommand}} (Pilot){{/if}}{{#if isOpenPilotCommand}} (Pilot){{/if}}{{#if isBetaCommand}} (Beta){{/if}}{{#if deprecated}} (Deprecated){{/if}}</ph></title>
-    <shortdesc><ph id="shortdesc">{{#if deprecated}}The command <codeph otherprops="nolang">{{id}}</codeph> has been deprecated and will be removed in v{{nextVersion deprecated.version}}.0 or later. Use <codeph otherprops="nolang">{{deprecated.to}}</codeph> instead. {{/if}}{{#if longDescription}}{{longDescription}}{{else}}{{description}}{{/if}}</ph></shortdesc>
+    <shortdesc><ph id="shortdesc">{{#if deprecated}}The command <codeph otherprops="nolang">{{id}}</codeph> has been deprecated and will be removed in v{{nextVersion deprecated.version}}.0 or later. Use <codeph otherprops="nolang">{{deprecated.to}}</codeph> instead. {{/if}}{{description}}</ph></shortdesc>
     <prolog>
         <metadata>
             {{!--In the future we’ll add keywords here.--}}
@@ -81,7 +81,7 @@ IF YOU WANT TO CHANGE THIS CONTENT, CONTACT rsears@salesforce.com FOR DETAILS.
                     <dt>{{#if char}}<codeph otherprops="nolang">-{{char}}</codeph> | {{/if}}<codeph otherprops="nolang">--{{name}}</codeph>{{#if hasValue}} <parmname>{{toUpperCase name}}</parmname>{{/if}}</dt>
                     {{#if deprecated}}<dd>The parameter <codeph otherprops="nolang">--{{name}}</codeph> has been deprecated and will be removed in v{{nextVersion deprecated.version}}.0 or later. Use <codeph otherprops="nolang">{{deprecated.to}}</codeph> instead.</dd>
                     {{/if}}<dd>{{#if optional}}Optional{{else}}Required{{/if}}</dd>
-                    <dd>{{#if longDescriptionPs}}{{#each longDescriptionPs}}<p>{{[]}}</p>{{/each}}{{else}}<p>{{description}}</p>{{/if}}</dd>{{#if kind}}
+                    <dd><p>{{description}}</p></dd>{{#if kind}}
                     <dd>Type: {{kind}}</dd>{{/if}}{{#if options}}
                     <dd>Permissible values are: {{join options}}</dd>{{/if}}{{#if default}}
                     <dd>Default value: {{default}}</dd>{{/if}}
@@ -90,11 +90,13 @@ IF YOU WANT TO CHANGE THIS CONTENT, CONTACT rsears@salesforce.com FOR DETAILS.
             </dl>
         </section>
         {{/if}}
+        {{#if help}}
         <section>
             <title><ph>Help for <codeph otherprops="nolang">{{id}}</codeph></ph></title>
-            {{#each helpPs}}
+            {{#each help}}
             {{#isCodeBlock this}}<codeblock otherprops="nolang">{{this}}</codeblock>{{else}}<p>{{this}}</p>{{/isCodeBlock}}
             {{/each}}
         </section>
+        {{/if}}
     </refbody>
 </reference>

test/utils.test.ts

@@ -46,7 +46,7 @@ describe('punctuate', () => {
 
   it('multi line descriptions to longDescriptions', () => {
     expect(punctuate(`lowercase oclif description${EOL}${EOL}some other stuff`)).to.equal(
-      `Lowercase oclif description.${EOL}${EOL}some other stuff`
+      'Lowercase oclif description.'
     );
   });