Update Office Extension to API Documenter (microsoft#575)

kbrandl · pgonzal · commit 5b6b8a01fada · 2018-03-21T12:28:18.000-07:00
* Minor changes to OfficeYamlDocumenter.ts for autogeneration of Office Add-ins docs.

* Fix typo in regex.

* Change sequence of regex checks.

* Change 'Api set' to 'API set'.

* Add change logs.

* Fix issues reported by tslint.

* Update email address in change logs.
diff --git a/apps/api-documenter/src/yaml/OfficeYamlDocumenter.ts b/apps/api-documenter/src/yaml/OfficeYamlDocumenter.ts
@@ -63,26 +63,43 @@ export class OfficeYamlDocumenter extends YamlDocumenter {
         yamlItem.remarks = '';
       }
 
-      yamlItem.remarks += '\n\n## Snippets\n';
+      yamlItem.remarks += '\n\n#### Examples\n';
       for (const snippet of snippets) {
-        yamlItem.remarks += '\n```typescript\n' + snippet + '\n```\n';
+        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.summary = this._fixupApiSet(yamlItem.summary, yamlItem.uid);
     }
     if (yamlItem.remarks) {
-      yamlItem.remarks = this._fixupApiSet(yamlItem.remarks);
+      yamlItem.remarks = this._fixupApiSet(yamlItem.remarks, yamlItem.uid);
     }
   }
 
-  private _fixupApiSet(markup: string): string {
+  private _fixupApiSet(markup: string, uid: string): string {
     // Search for a pattern such as this:
     // \[Api set: ExcelApi 1.1\]
     //
     // Hyperlink it like this:
-    // \[ [Api set: ExcelApi 1.1](http://bing.com) \]
-    return markup.replace(/\\\[(Api set:[^\]]+)\\\]/, `\\[ [$1](http://bing.com) \\]`);
+    // \[ [API set: ExcelApi 1.1](http://bing.com?type=excel) \]
+    markup = markup.replace(/Api/, 'API');
+    if (uid.search(/Excel/i) !== -1) {
+      return markup.replace(/\\\[(API set:[^\]]+)\\\]/, `\\[ [$1](http://bing.com?type=excel) \\]`);
+    } else if (uid.search(/OneNote/i) !== -1) {
+      return markup.replace(/\\\[(API set:[^\]]+)\\\]/, `\\[ [$1](http://bing.com?type=onenote) \\]`);
+    } else if (uid.search(/Visio/i) !== -1) {
+      return markup.replace(/\\\[(API set:[^\]]+)\\\]/, `\\[ [$1](http://bing.com?type=visio) \\]`);
+    } else if (uid.search(/Outlook/i) !== -1) {
+      return markup.replace(/\\\[(API set:[^\]]+)\\\]/, `\\[ [$1](http://bing.com?type=outlook) \\]`);
+    } else if (uid.search(/Word/i) !== -1) {
+      return markup.replace(/\\\[(API set:[^\]]+)\\\]/, `\\[ [$1](http://bing.com?type=word) \\]`);
+    } else {
+      return markup.replace(/\\\[(API set:[^\]]+)\\\]/, `\\[ [$1](http://bing.com) \\]`);
+    }
   }
 }
diff --git a/common/changes/@microsoft/api-documenter/kbrandl-patch-1_2018-03-21-12-52.json b/common/changes/@microsoft/api-documenter/kbrandl-patch-1_2018-03-21-12-52.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-documenter",
+      "comment": "Change heading for code snippets section from `## Snippets` to `#### Examples`.",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/api-documenter",
+  "email": "kibrandl@users.noreply.github.com"
+}
diff --git a/common/changes/@microsoft/api-documenter/kbrandl-patch-1_2018-03-21-12-53.json b/common/changes/@microsoft/api-documenter/kbrandl-patch-1_2018-03-21-12-53.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-documenter",
+      "comment": "Customize the `API Set #.#` hyperlink target by host. ",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/api-documenter",
+  "email": "kibrandl@users.noreply.github.com"
+}
diff --git a/common/changes/@microsoft/api-documenter/kbrandl-patch-1_2018-03-21-12-54.json b/common/changes/@microsoft/api-documenter/kbrandl-patch-1_2018-03-21-12-54.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-documenter",
+      "comment": "Designate proper language for each code snippet (TypeScript or JavaScript).",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/api-documenter",
+  "email": "kibrandl@users.noreply.github.com"
+}
