[api-documenter] Office Extension: Adding logic to remove added escape characters from code lines (microsoft#734)

AlexJerabek · Nicholas Pape · commit 647aca55828b · 2018-07-11T15:11:20.000-07:00
* Adding logic to remove added escape characters from code lines

* Adding change log
diff --git a/apps/api-documenter/src/yaml/OfficeYamlDocumenter.ts b/apps/api-documenter/src/yaml/OfficeYamlDocumenter.ts
@@ -68,25 +68,6 @@ export class OfficeYamlDocumenter extends YamlDocumenter {
 
   protected onCustomizeYamlItem(yamlItem: IYamlItem): void { // override
     const nameWithoutPackage: string = yamlItem.uid.replace(/^[^.]+\./, '');
-
-    const snippets: string[] | undefined = this._snippets[nameWithoutPackage];
-    if (snippets) {
-      delete this._snippets[nameWithoutPackage];
-
-      if (!yamlItem.remarks) {
-        yamlItem.remarks = '';
-      }
-
-      yamlItem.remarks += '\n\n#### Examples\n';
-      for (const snippet of snippets) {
-        if (snippet.search(/await/) === -1) {
-          yamlItem.remarks += '\n```javascript\n' + snippet + '\n```\n';
-        } else {
-          yamlItem.remarks += '\n```typescript\n' + snippet + '\n```\n';
-        }
-      }
-    }
-
     if (yamlItem.summary) {
       yamlItem.summary = this._fixupApiSet(yamlItem.summary, yamlItem.uid);
       yamlItem.summary = this._fixBoldAndItalics(yamlItem.summary);
@@ -96,7 +77,7 @@ export class OfficeYamlDocumenter extends YamlDocumenter {
       yamlItem.remarks = this._fixupApiSet(yamlItem.remarks, yamlItem.uid);
       yamlItem.remarks = this._fixBoldAndItalics(yamlItem.remarks);
       yamlItem.remarks = this._fixCodeTicks(yamlItem.remarks);
-      yamlItem.remarks = this._fixCodeArrows(yamlItem.remarks);
+      yamlItem.remarks = this._fixEscapedCode(yamlItem.remarks);
     }
     if (yamlItem.syntax && yamlItem.syntax.parameters) {
       yamlItem.syntax.parameters.forEach(part => {
@@ -106,6 +87,24 @@ export class OfficeYamlDocumenter extends YamlDocumenter {
           }
       });
     }
+
+    const snippets: string[] | undefined = this._snippets[nameWithoutPackage];
+    if (snippets) {
+      delete this._snippets[nameWithoutPackage];
+
+      if (!yamlItem.remarks) {
+        yamlItem.remarks = '';
+      }
+
+      yamlItem.remarks += '\n\n#### Examples\n';
+      for (const snippet of snippets) {
+        if (snippet.search(/await/) === -1) {
+          yamlItem.remarks += '\n```javascript\n' + snippet + '\n```\n';
+        } else {
+          yamlItem.remarks += '\n```typescript\n' + snippet + '\n```\n';
+        }
+      }
+    }
   }
 
   private _fixupApiSet(markup: string, uid: string): string {
@@ -137,7 +136,16 @@ export class OfficeYamlDocumenter extends YamlDocumenter {
     return Text.replaceAll(text, '\\`', '`');
   }
 
-  private _fixCodeArrows(text: string): string {
-    return Text.replaceAll(text, '=&gt;', '=>');
+  private _fixEscapedCode(text: string): string {
+    const backtickIndex: number = text.indexOf('`');
+    if (text.indexOf('`', backtickIndex) > 0) {
+      text = Text.replaceAll(text, '=&gt;', '=>');
+      let x: number = text.indexOf('\\', backtickIndex);
+      while (x >= 0) {
+        text = text.replace(/\\([^\\])/, '$1');
+        x = text.indexOf('\\', x + 1);
+      }
+    }
+    return text;
   }
 }
diff --git a/common/changes/@microsoft/api-documenter/AlexJ-CodeEscape_2018-07-03-16-53.json b/common/changes/@microsoft/api-documenter/AlexJ-CodeEscape_2018-07-03-16-53.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-documenter",
+      "comment": "Changing Office's APIExtractor add-on to unescape characters in code blocks",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/api-documenter",
+  "email": "AlexJerabek@users.noreply.github.com"
+}
