@microsoft/api-documenter - npm Package Compare versions

Comparing version 1.0.0 to 1.0.1

CHANGELOG.json

@@ -5,2 +5,23 @@ {
     {
+      "version": "1.0.1",
+      "tag": "@microsoft/api-documenter_v1.0.1",
+      "date": "Tue, 24 Oct 2017 18:17:12 GMT",
+      "comments": {
+        "dependency": [
+          {
+            "comment": "Updating dependency \"@microsoft/api-extractor\" from `4.1.1` to `4.1.2`"
+          },
+          {
+            "comment": "Updating dependency \"@microsoft/node-core-library\" from `~0.3.8` to `~0.3.9`"
+          },
+          {
+            "comment": "Updating dependency \"@microsoft/ts-command-line\" from `~2.1.1` to `~2.1.2`"
+          },
+          {
+            "comment": "Updating dependency \"@microsoft/node-library-build\" from `~4.1.6` to `~4.2.0`"
+          }
+        ]
+      }
+    },
+    {
       "version": "1.0.0",
@@ -7,0 +28,0 @@ "tag": "@microsoft/api-documenter_v1.0.0",

CHANGELOG.md

 # Change Log - @microsoft/api-documenter
 
-This log was last generated on Mon, 23 Oct 2017 21:53:12 GMT and should not be manually modified.
+This log was last generated on Tue, 24 Oct 2017 18:17:12 GMT and should not be manually modified.
 
+## 1.0.1
+Tue, 24 Oct 2017 18:17:12 GMT
+
+*Changes not tracked*
+
 ## 1.0.0
@@ -6,0 +11,0 @@ Mon, 23 Oct 2017 21:53:12 GMT

lib/cli/YamlAction.d.ts

 import { ApiDocumenterCommandLine } from './ApiDocumenterCommandLine';
 import { BaseAction } from './BaseAction';
 export declare class YamlAction extends BaseAction {
+    private _officeParameter;
     constructor(parser: ApiDocumenterCommandLine);
+    protected onDefineParameters(): void;
     protected onExecute(): void;
 }

lib/cli/YamlAction.js

@@ -7,2 +7,3 @@ "use strict";
 const YamlDocumenter_1 = require("../yaml/YamlDocumenter");
+const OfficeYamlDocumenter_1 = require("../yaml/OfficeYamlDocumenter");
 class YamlAction extends BaseAction_1.BaseAction {
@@ -18,5 +19,14 @@ constructor(parser) {
     }
+    onDefineParameters() {
+        super.onDefineParameters();
+        this._officeParameter = this.defineFlagParameter({
+            parameterLongName: '--office',
+            description: `Enables some additional features specific to Office Add-ins`
+        });
+    }
     onExecute() {
         const docItemSet = this.buildDocItemSet();
-        const yamlDocumenter = new YamlDocumenter_1.YamlDocumenter(docItemSet);
+        const yamlDocumenter = this._officeParameter.value
+            ? new OfficeYamlDocumenter_1.OfficeYamlDocumenter(docItemSet, this.inputFolder)
+            : new YamlDocumenter_1.YamlDocumenter(docItemSet);
         yamlDocumenter.generateFiles(this.outputFolder);
@@ -23,0 +33,0 @@ }

lib/utils/DocItemSet.d.ts

 import { ApiItem, IApiItemReference } from '@microsoft/api-extractor';
 export declare enum DocItemKind {
     Package = 0,
-    Class = 1,
-    Interface = 2,
-    Method = 3,
-    Constructor = 4,
-    Function = 5,
-    Property = 6,
-    Enum = 7,
-    EnumMember = 8,
+    Namespace = 1,
+    Class = 2,
+    Interface = 3,
+    Method = 4,
+    Constructor = 5,
+    Function = 6,
+    Property = 7,
+    Enum = 8,
+    EnumMember = 9,
 }
@@ -45,8 +46,2 @@ /**
     tryGetChild(name: string): DocItem | undefined;
-    /**
-     * Returns true if this is a package, and it has been classified as "external",
-     * i.e. a system library that is maintained by an external party, but included in the
-     * documentation for informational purposes.
-     */
-    readonly isExternalPackage: boolean;
 }
@@ -53,0 +48,0 @@ /**

lib/utils/DocItemSet.js

@@ -10,10 +10,11 @@ "use strict";
     DocItemKind[DocItemKind["Package"] = 0] = "Package";
-    DocItemKind[DocItemKind["Class"] = 1] = "Class";
-    DocItemKind[DocItemKind["Interface"] = 2] = "Interface";
-    DocItemKind[DocItemKind["Method"] = 3] = "Method";
-    DocItemKind[DocItemKind["Constructor"] = 4] = "Constructor";
-    DocItemKind[DocItemKind["Function"] = 5] = "Function";
-    DocItemKind[DocItemKind["Property"] = 6] = "Property";
-    DocItemKind[DocItemKind["Enum"] = 7] = "Enum";
-    DocItemKind[DocItemKind["EnumMember"] = 8] = "EnumMember";
+    DocItemKind[DocItemKind["Namespace"] = 1] = "Namespace";
+    DocItemKind[DocItemKind["Class"] = 2] = "Class";
+    DocItemKind[DocItemKind["Interface"] = 3] = "Interface";
+    DocItemKind[DocItemKind["Method"] = 4] = "Method";
+    DocItemKind[DocItemKind["Constructor"] = 5] = "Constructor";
+    DocItemKind[DocItemKind["Function"] = 6] = "Function";
+    DocItemKind[DocItemKind["Property"] = 7] = "Property";
+    DocItemKind[DocItemKind["Enum"] = 8] = "Enum";
+    DocItemKind[DocItemKind["EnumMember"] = 9] = "EnumMember";
 })(DocItemKind = exports.DocItemKind || (exports.DocItemKind = {}));
@@ -45,3 +46,4 @@ /**
             case 'package':
-                this.kind = DocItemKind.Package;
+            case 'namespace':
+                this.kind = this.apiItem.kind === 'package' ? DocItemKind.Package : DocItemKind.Namespace;
                 for (const exportName of Object.keys(this.apiItem.exports)) {
@@ -137,11 +139,2 @@ const child = this.apiItem.exports[exportName];
     }
-    /**
-     * Returns true if this is a package, and it has been classified as "external",
-     * i.e. a system library that is maintained by an external party, but included in the
-     * documentation for informational purposes.
-     */
-    get isExternalPackage() {
-        // We should define a better criteria for this
-        return this.apiItem.kind === 'package' && this.apiItem.name.substr(0, 1) === '@';
-    }
 }
@@ -148,0 +141,0 @@ exports.DocItem = DocItem;

lib/yaml/YamlDocumenter.d.ts

 import { DocItemSet } from '../utils/DocItemSet';
+import { IYamlItem } from './IYamlApiFile';
+import { IYamlTocItem } from './IYamlTocFile';
 /**
@@ -10,3 +12,6 @@ * Writes documentation in the Universal Reference YAML file format, as defined by typescript.schema.json.
     generateFiles(outputFolder: string): void;
+    protected onGetTocRoot(): IYamlTocItem;
+    protected onCustomizeYamlItem(yamlItem: IYamlItem): void;
     private _visitDocItems(docItem, parentYamlFile);
+    private _flattenNamespaces(items);
     /**
@@ -30,4 +35,5 @@ * Write the table of contents
     private _getUid(docItem);
+    private _getYamlItemName(docItem);
     private _getYamlFilePath(docItem);
     private _deleteOldOutputFiles();
 }

lib/yaml/YamlDocumenter.js

@@ -30,2 +30,12 @@ "use strict";
     }
+    onGetTocRoot() {
+        return {
+            name: 'SharePoint Framework',
+            href: '~/overview/sharepoint.md',
+            items: []
+        };
+    }
+    onCustomizeYamlItem(yamlItem) {
+        // (overridden by child class)
+    }
     _visitDocItems(docItem, parentYamlFile) {
@@ -36,2 +46,3 @@ const yamlItem = this._generateYamlItem(docItem);
         }
+        this.onCustomizeYamlItem(yamlItem);
         if (this._shouldEmbed(docItem.kind)) {
@@ -48,3 +59,4 @@ if (!parentYamlFile) {
             newYamlFile.items.push(yamlItem);
-            for (const child of docItem.children) {
+            const flattenedChildren = this._flattenNamespaces(docItem.children);
+            for (const child of flattenedChildren) {
                 if (this._visitDocItems(child, newYamlFile)) {
@@ -68,3 +80,3 @@ if (!yamlItem.children) {
                     uid: this._getUid(docItem),
-                    name: docItem.name
+                    name: this._getYamlItemName(docItem)
                 });
@@ -75,2 +87,16 @@ }
     }
+    // Since the YAML schema does not yet support nested namespaces, we simply omit them from
+    // the tree.  However, _getYamlItemName() will show the namespace.
+    _flattenNamespaces(items) {
+        const flattened = [];
+        for (const item of items) {
+            if (item.kind === DocItemSet_1.DocItemKind.Namespace) {
+                flattened.push(...this._flattenNamespaces(item.children));
+            }
+            else {
+                flattened.push(item);
+            }
+        }
+        return flattened;
+    }
     /**
@@ -83,22 +109,5 @@ * Write the table of contents
         };
-        tocFile.items.push({
-            name: 'SharePoint Framework',
-            items: [
-                {
-                    name: 'Overview',
-                    href: './index.md'
-                }
-            ].concat(this._buildTocItems(docItems.filter(x => x.isExternalPackage)))
-        });
-        const externalPackages = docItems.filter(x => !x.isExternalPackage);
-        if (externalPackages.length) {
-            tocFile.items.push({
-                name: '─────────────'
-            });
-            tocFile.items.push({
-                name: 'External Packages',
-                items: this._buildTocItems(externalPackages)
-            });
-        }
-        this._buildTocItems(docItems);
+        const rootItem = this.onGetTocRoot();
+        tocFile.items.push(rootItem);
+        rootItem.items.push(...this._buildTocItems(docItems));
         const tocFilePath = path.join(this._outputFolder, 'toc.yml');
@@ -111,10 +120,19 @@ console.log('Writing ' + tocFilePath);
         for (const docItem of docItems) {
-            if (this._shouldEmbed(docItem.kind)) {
-                // Don't generate table of contents items for embedded definitions
-                continue;
+            let tocItem;
+            if (docItem.kind === DocItemSet_1.DocItemKind.Namespace) {
+                // Namespaces don't have nodes yet
+                tocItem = {
+                    name: Utilities_1.Utilities.getUnscopedPackageName(docItem.name)
+                };
             }
-            const tocItem = {
-                name: Utilities_1.Utilities.getUnscopedPackageName(docItem.name),
-                uid: this._getUid(docItem)
-            };
+            else {
+                if (this._shouldEmbed(docItem.kind)) {
+                    // Don't generate table of contents items for embedded definitions
+                    continue;
+                }
+                tocItem = {
+                    name: Utilities_1.Utilities.getUnscopedPackageName(docItem.name),
+                    uid: this._getUid(docItem)
+                };
+            }
             tocItems.push(tocItem);
@@ -156,3 +174,3 @@ const childItems = this._buildTocItems(docItem.children);
         }
-        yamlItem.name = docItem.name;
+        yamlItem.name = this._getYamlItemName(docItem);
         yamlItem.fullName = yamlItem.uid;
@@ -314,2 +332,10 @@ yamlItem.langs = ['typeScript'];
     }
+    _getYamlItemName(docItem) {
+        if (docItem.parent && docItem.parent.kind === DocItemSet_1.DocItemKind.Namespace) {
+            // For members a namespace, show the full name excluding the package part:
+            // Example: excel.Excel.Binding --> Excel.Binding
+            return this._getUid(docItem).replace(/^[^.]+\./, '');
+        }
+        return docItem.name;
+    }
     _getYamlFilePath(docItem) {
@@ -316,0 +342,0 @@ let result = '';

package.json

 {
   "name": "@microsoft/api-documenter",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Read JSON files from api-extractor, generate documentation pages",
@@ -20,5 +20,5 @@ "repository": {
   "dependencies": {
-    "@microsoft/api-extractor": "4.1.1",
-    "@microsoft/node-core-library": "~0.3.8",
-    "@microsoft/ts-command-line": "~2.1.1",
+    "@microsoft/api-extractor": "4.1.2",
+    "@microsoft/node-core-library": "~0.3.9",
+    "@microsoft/ts-command-line": "~2.1.2",
     "colors": "~1.1.2",
@@ -29,13 +29,10 @@ "fs-extra": "~0.26.7",
   "devDependencies": {
-    "@microsoft/node-library-build": "~4.1.6",
-    "@types/chai": "3.4.34",
+    "@microsoft/node-library-build": "~4.2.0",
     "@types/colors": "1.1.3",
     "@types/fs-extra": "0.0.37",
     "@types/js-yaml": "3.9.1",
-    "@types/mocha": "2.2.38",
     "@types/node": "6.0.88",
-    "chai": "~3.5.0",
     "gulp": "~3.9.1",
-    "mocha": "~3.4.2"
+    "@types/jest": "~20.0.4"
   }
 }

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

247565

increased by5.33%

Dev dependency count

7

decreased by-30%

Number of package files

49

increased by6.52%

Lines of code

2502

increased by5.53%

Number of medium supply chain risk alerts

0

decreased by-100%

Worsened metrics

Number of low supply chain risk alerts

5

increased by25%

Dependency changes

• + Added@microsoft/api-extractor@4.1.2(transitive)

• - Removed@microsoft/api-extractor@4.1.1(transitive)

• Updated@microsoft/api-extractor@4.1.2

• Updated@microsoft/node-core-library@~0.3.9

• Updated@microsoft/ts-command-line@~2.1.2