@microsoft/api-documenter - npm Package Compare versions

Comparing version 1.5.4 to 1.5.5

CHANGELOG.json

@@ -5,2 +5,14 @@ {
     {
+      "version": "1.5.5",
+      "tag": "@microsoft/api-documenter_v1.5.5",
+      "date": "Wed, 01 Aug 2018 21:02:43 GMT",
+      "comments": {
+        "patch": [
+          {
+            "comment": "Updating OfficeYamlDocumenter to append snippets to non-empty sections"
+          }
+        ]
+      }
+    },
+    {
       "version": "1.5.4",
@@ -7,0 +19,0 @@ "tag": "@microsoft/api-documenter_v1.5.4",

CHANGELOG.md

 # Change Log - @microsoft/api-documenter
 
-This log was last generated on Thu, 26 Jul 2018 23:53:43 GMT and should not be manually modified.
+This log was last generated on Wed, 01 Aug 2018 21:02:43 GMT and should not be manually modified.
 
+## 1.5.5
+Wed, 01 Aug 2018 21:02:43 GMT
+
+### Patches
+
+- Updating OfficeYamlDocumenter to append snippets to non-empty sections
+
 ## 1.5.4
@@ -6,0 +13,0 @@ Thu, 26 Jul 2018 23:53:43 GMT

lib/yaml/OfficeYamlDocumenter.d.ts

@@ -21,2 +21,3 @@ import { DocItemSet } from '../utils/DocItemSet';
     private _fixEscapedCode(text);
+    private _generateExampleSnippetText(snippets);
 }

lib/yaml/OfficeYamlDocumenter.js

@@ -70,14 +70,15 @@ "use strict";
             delete this._snippets[nameWithoutPackage];
-            if (!yamlItem.remarks) {
-                yamlItem.remarks = '';
+            const snippetText = this._generateExampleSnippetText(snippets);
+            if (yamlItem.remarks) {
+                yamlItem.remarks += snippetText;
             }
-            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 if (yamlItem.syntax && yamlItem.syntax.return) {
+                if (!yamlItem.syntax.return.description) {
+                    yamlItem.syntax.return.description = '';
                 }
-                else {
-                    yamlItem.remarks += '\n```typescript\n' + snippet + '\n```\n';
-                }
+                yamlItem.syntax.return.description += snippetText;
             }
+            else {
+                yamlItem.remarks = snippetText;
+            }
         }
@@ -122,2 +123,16 @@ }
     }
+    _generateExampleSnippetText(snippets) {
+        const text = ['\n#### Examples\n'];
+        for (const snippet of snippets) {
+            if (snippet.search(/await/) === -1) {
+                text.push('```javascript');
+            }
+            else {
+                text.push('```typescript');
+            }
+            text.push(snippet);
+            text.push('```');
+        }
+        return text.join('\n');
+    }
 }
@@ -124,0 +139,0 @@ exports.OfficeYamlDocumenter = OfficeYamlDocumenter;

lib/yaml/OfficeYamlDocumenter.js.map

@@ -1,1 +0,1 @@
-{"version":3,"sources":["yaml/OfficeYamlDocumenter.ts"],"names":[],"mappings":"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","file":"OfficeYamlDocumenter.js","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\r\n// See LICENSE in the project root for license information.\r\n\r\nimport * as colors from 'colors';\r\nimport * as path from 'path';\r\nimport yaml = require('js-yaml');\r\n\r\nimport { DocItemSet } from '../utils/DocItemSet';\r\nimport { IYamlTocItem } from './IYamlTocFile';\r\nimport { IYamlItem } from './IYamlApiFile';\r\nimport { YamlDocumenter } from './YamlDocumenter';\r\nimport { Text, FileSystem } from '@microsoft/node-core-library';\r\n\r\ninterface ISnippetsFile {\r\n  /**\r\n   * The keys are API names like \"Excel.Range.clear\".\r\n   * The values are TypeScript source code excerpts.\r\n   */\r\n  [apiName: string]: string[];\r\n}\r\n\r\n/**\r\n * Extends YamlDocumenter with some custom logic that is specific to Office Add-ins.\r\n */\r\nexport class OfficeYamlDocumenter extends YamlDocumenter {\r\n  private _snippets: ISnippetsFile;\r\n\r\n  // Default API Set URL when no product match is found.\r\n  private _apiSetUrlDefault: string = '/javascript/office/javascript-api-for-office';\r\n\r\n  // Hash set of API Set URLs based on product.\r\n  private _apiSetUrls: Object = {\r\n    'Excel': '/javascript/office/requirement-sets/excel-api-requirement-sets',\r\n    'OneNote': '/javascript/office/requirement-sets/onenote-api-requirement-sets',\r\n    'Visio': '/javascript/office/overview/visio-javascript-reference-overview',\r\n    'Outlook': '/javascript/office/requirement-sets/outlook-api-requirement-sets',\r\n    'Word': '/javascript/office/requirement-sets/word-api-requirement-sets'\r\n  };\r\n\r\n  public constructor(docItemSet: DocItemSet, inputFolder: string) {\r\n    super(docItemSet);\r\n\r\n    const snippetsFilePath: string = path.join(inputFolder, 'snippets.yaml');\r\n\r\n    console.log('Loading snippets from ' + snippetsFilePath);\r\n\r\n    const snippetsContent: string = FileSystem.readFile(snippetsFilePath);\r\n    this._snippets = yaml.load(snippetsContent, { filename: snippetsFilePath });\r\n  }\r\n\r\n  public generateFiles(outputFolder: string): void { // override\r\n    super.generateFiles(outputFolder);\r\n\r\n    // After we generate everything, check for any unused snippets\r\n    console.log();\r\n    for (const apiName of Object.keys(this._snippets)) {\r\n      console.error(colors.yellow('Warning: Unused snippet ' + apiName));\r\n    }\r\n  }\r\n\r\n  protected onGetTocRoot(): IYamlTocItem { // override\r\n    return {\r\n      name: 'API reference',\r\n      href: '~/docs-ref-autogen/overview/office.md',\r\n      items: [ ]\r\n    };\r\n  }\r\n\r\n  protected onCustomizeYamlItem(yamlItem: IYamlItem): void { // override\r\n    const nameWithoutPackage: string = yamlItem.uid.replace(/^[^.]+\\./, '');\r\n    if (yamlItem.summary) {\r\n      yamlItem.summary = this._fixupApiSet(yamlItem.summary, yamlItem.uid);\r\n      yamlItem.summary = this._fixBoldAndItalics(yamlItem.summary);\r\n      yamlItem.summary = this._fixCodeTicks(yamlItem.summary);\r\n    }\r\n    if (yamlItem.remarks) {\r\n      yamlItem.remarks = this._fixupApiSet(yamlItem.remarks, yamlItem.uid);\r\n      yamlItem.remarks = this._fixBoldAndItalics(yamlItem.remarks);\r\n      yamlItem.remarks = this._fixCodeTicks(yamlItem.remarks);\r\n      yamlItem.remarks = this._fixEscapedCode(yamlItem.remarks);\r\n    }\r\n    if (yamlItem.syntax && yamlItem.syntax.parameters) {\r\n      yamlItem.syntax.parameters.forEach(part => {\r\n          if (part.description) {\r\n            part.description = this._fixCodeTicks(part.description);\r\n            part.description = this._fixBoldAndItalics(part.description);\r\n          }\r\n      });\r\n    }\r\n\r\n    const snippets: string[] | undefined = this._snippets[nameWithoutPackage];\r\n    if (snippets) {\r\n      delete this._snippets[nameWithoutPackage];\r\n\r\n      if (!yamlItem.remarks) {\r\n        yamlItem.remarks = '';\r\n      }\r\n\r\n      yamlItem.remarks += '\\n\\n#### Examples\\n';\r\n      for (const snippet of snippets) {\r\n        if (snippet.search(/await/) === -1) {\r\n          yamlItem.remarks += '\\n```javascript\\n' + snippet + '\\n```\\n';\r\n        } else {\r\n          yamlItem.remarks += '\\n```typescript\\n' + snippet + '\\n```\\n';\r\n        }\r\n      }\r\n    }\r\n  }\r\n\r\n  private _fixupApiSet(markup: string, uid: string): string {\r\n    // Search for a pattern such as this:\r\n    // \\[Api set: ExcelApi 1.1\\]\r\n    //\r\n    // Hyperlink it like this:\r\n    // \\[ [API set: ExcelApi 1.1](http://bing.com?type=excel) \\]\r\n    markup = markup.replace(/Api/, 'API');\r\n    return markup.replace(/\\\\\\[(API set:[^\\]]+)\\\\\\]/, '\\\\[ [$1](' + this._getApiSetUrl(uid) + ') \\\\]');\r\n  }\r\n\r\n  // Gets the link to the API set based on product context. Seeks a case-insensitve match in the hash set.\r\n  private _getApiSetUrl(uid: string): string {\r\n    for (const key of Object.keys(this._apiSetUrls)) {\r\n      const regexp: RegExp = new RegExp(key, 'i');\r\n      if (regexp.test(uid)) {\r\n          return this._apiSetUrls[key];\r\n      }\r\n    }\r\n    return this._apiSetUrlDefault; // match not found.\r\n  }\r\n\r\n  private _fixBoldAndItalics(text: string): string {\r\n    return Text.replaceAll(text, '\\\\*', '*');\r\n  }\r\n\r\n  private _fixCodeTicks(text: string): string {\r\n    return Text.replaceAll(text, '\\\\`', '`');\r\n  }\r\n\r\n  private _fixEscapedCode(text: string): string {\r\n    const backtickIndex: number = text.indexOf('`');\r\n    if (text.indexOf('`', backtickIndex) > 0) {\r\n      text = Text.replaceAll(text, '=>', '=>');\r\n      let x: number = text.indexOf('\\\\', backtickIndex);\r\n      while (x >= 0) {\r\n        text = text.replace(/\\\\([^\\\\])/, '$1');\r\n        x = text.indexOf('\\\\', x + 1);\r\n      }\r\n    }\r\n    return text;\r\n  }\r\n}"],"sourceRoot":"../../../src"}
+{"version":3,"sources":["yaml/OfficeYamlDocumenter.ts"],"names":[],"mappings":"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","file":"OfficeYamlDocumenter.js","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\r\n// See LICENSE in the project root for license information.\r\n\r\nimport * as colors from 'colors';\r\nimport * as path from 'path';\r\nimport yaml = require('js-yaml');\r\n\r\nimport { DocItemSet } from '../utils/DocItemSet';\r\nimport { IYamlTocItem } from './IYamlTocFile';\r\nimport { IYamlItem } from './IYamlApiFile';\r\nimport { YamlDocumenter } from './YamlDocumenter';\r\nimport { Text, FileSystem } from '@microsoft/node-core-library';\r\n\r\ninterface ISnippetsFile {\r\n  /**\r\n   * The keys are API names like \"Excel.Range.clear\".\r\n   * The values are TypeScript source code excerpts.\r\n   */\r\n  [apiName: string]: string[];\r\n}\r\n\r\n/**\r\n * Extends YamlDocumenter with some custom logic that is specific to Office Add-ins.\r\n */\r\nexport class OfficeYamlDocumenter extends YamlDocumenter {\r\n  private _snippets: ISnippetsFile;\r\n\r\n  // Default API Set URL when no product match is found.\r\n  private _apiSetUrlDefault: string = '/javascript/office/javascript-api-for-office';\r\n\r\n  // Hash set of API Set URLs based on product.\r\n  private _apiSetUrls: Object = {\r\n    'Excel': '/javascript/office/requirement-sets/excel-api-requirement-sets',\r\n    'OneNote': '/javascript/office/requirement-sets/onenote-api-requirement-sets',\r\n    'Visio': '/javascript/office/overview/visio-javascript-reference-overview',\r\n    'Outlook': '/javascript/office/requirement-sets/outlook-api-requirement-sets',\r\n    'Word': '/javascript/office/requirement-sets/word-api-requirement-sets'\r\n  };\r\n\r\n  public constructor(docItemSet: DocItemSet, inputFolder: string) {\r\n    super(docItemSet);\r\n\r\n    const snippetsFilePath: string = path.join(inputFolder, 'snippets.yaml');\r\n\r\n    console.log('Loading snippets from ' + snippetsFilePath);\r\n\r\n    const snippetsContent: string = FileSystem.readFile(snippetsFilePath);\r\n    this._snippets = yaml.load(snippetsContent, { filename: snippetsFilePath });\r\n  }\r\n\r\n  public generateFiles(outputFolder: string): void { // override\r\n    super.generateFiles(outputFolder);\r\n\r\n    // After we generate everything, check for any unused snippets\r\n    console.log();\r\n    for (const apiName of Object.keys(this._snippets)) {\r\n      console.error(colors.yellow('Warning: Unused snippet ' + apiName));\r\n    }\r\n  }\r\n\r\n  protected onGetTocRoot(): IYamlTocItem { // override\r\n    return {\r\n      name: 'API reference',\r\n      href: '~/docs-ref-autogen/overview/office.md',\r\n      items: [ ]\r\n    };\r\n  }\r\n\r\n  protected onCustomizeYamlItem(yamlItem: IYamlItem): void { // override\r\n    const nameWithoutPackage: string = yamlItem.uid.replace(/^[^.]+\\./, '');\r\n    if (yamlItem.summary) {\r\n      yamlItem.summary = this._fixupApiSet(yamlItem.summary, yamlItem.uid);\r\n      yamlItem.summary = this._fixBoldAndItalics(yamlItem.summary);\r\n      yamlItem.summary = this._fixCodeTicks(yamlItem.summary);\r\n    }\r\n    if (yamlItem.remarks) {\r\n      yamlItem.remarks = this._fixupApiSet(yamlItem.remarks, yamlItem.uid);\r\n      yamlItem.remarks = this._fixBoldAndItalics(yamlItem.remarks);\r\n      yamlItem.remarks = this._fixCodeTicks(yamlItem.remarks);\r\n      yamlItem.remarks = this._fixEscapedCode(yamlItem.remarks);\r\n    }\r\n    if (yamlItem.syntax && yamlItem.syntax.parameters) {\r\n      yamlItem.syntax.parameters.forEach(part => {\r\n          if (part.description) {\r\n            part.description = this._fixCodeTicks(part.description);\r\n            part.description = this._fixBoldAndItalics(part.description);\r\n          }\r\n      });\r\n    }\r\n\r\n    const snippets: string[] | undefined = this._snippets[nameWithoutPackage];\r\n    if (snippets) {\r\n      delete this._snippets[nameWithoutPackage];\r\n      const snippetText: string = this._generateExampleSnippetText(snippets);\r\n      if (yamlItem.remarks) {\r\n        yamlItem.remarks += snippetText;\r\n      } else if (yamlItem.syntax && yamlItem.syntax.return) {\r\n        if (!yamlItem.syntax.return.description) {\r\n          yamlItem.syntax.return.description = '';\r\n        }\r\n        yamlItem.syntax.return.description += snippetText;\r\n      } else {\r\n        yamlItem.remarks = snippetText;\r\n      }\r\n    }\r\n  }\r\n\r\n  private _fixupApiSet(markup: string, uid: string): string {\r\n    // Search for a pattern such as this:\r\n    // \\[Api set: ExcelApi 1.1\\]\r\n    //\r\n    // Hyperlink it like this:\r\n    // \\[ [API set: ExcelApi 1.1](http://bing.com?type=excel) \\]\r\n    markup = markup.replace(/Api/, 'API');\r\n    return markup.replace(/\\\\\\[(API set:[^\\]]+)\\\\\\]/, '\\\\[ [$1](' + this._getApiSetUrl(uid) + ') \\\\]');\r\n  }\r\n\r\n  // Gets the link to the API set based on product context. Seeks a case-insensitve match in the hash set.\r\n  private _getApiSetUrl(uid: string): string {\r\n    for (const key of Object.keys(this._apiSetUrls)) {\r\n      const regexp: RegExp = new RegExp(key, 'i');\r\n      if (regexp.test(uid)) {\r\n          return this._apiSetUrls[key];\r\n      }\r\n    }\r\n    return this._apiSetUrlDefault; // match not found.\r\n  }\r\n\r\n  private _fixBoldAndItalics(text: string): string {\r\n    return Text.replaceAll(text, '\\\\*', '*');\r\n  }\r\n\r\n  private _fixCodeTicks(text: string): string {\r\n    return Text.replaceAll(text, '\\\\`', '`');\r\n  }\r\n\r\n  private _fixEscapedCode(text: string): string {\r\n    const backtickIndex: number = text.indexOf('`');\r\n    if (text.indexOf('`', backtickIndex) > 0) {\r\n      text = Text.replaceAll(text, '=>', '=>');\r\n      let x: number = text.indexOf('\\\\', backtickIndex);\r\n      while (x >= 0) {\r\n        text = text.replace(/\\\\([^\\\\])/, '$1');\r\n        x = text.indexOf('\\\\', x + 1);\r\n      }\r\n    }\r\n    return text;\r\n  }\r\n\r\n  private _generateExampleSnippetText(snippets: string[]): string {\r\n    const text: string[] = ['\\n#### Examples\\n'];\r\n    for (const snippet of snippets) {\r\n      if (snippet.search(/await/) === -1) {\r\n        text.push('```javascript');\r\n\r\n      } else {\r\n        text.push('```typescript');\r\n      }\r\n\r\n      text.push(snippet);\r\n      text.push('```');\r\n    }\r\n    return text.join('\\n');\r\n  }\r\n}"],"sourceRoot":"../../../src"}

package.json

 {
   "name": "@microsoft/api-documenter",
-  "version": "1.5.4",
+  "version": "1.5.5",
   "description": "Read JSON files from api-extractor, generate documentation pages",
@@ -5,0 +5,0 @@ "repository": {

New alerts

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Fixed alerts

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

303442

0.67%

Lines of code

3978

0.71%

No dependency changes