@microsoft/api-extractor - npm Package Compare versions

Comparing version 1.1.3 to 1.1.4

CHANGELOG.json

@@ -5,2 +5,20 @@ {
     {
+      "version": "1.1.4",
+      "tag": "@microsoft/api-extractor_v1.1.4",
+      "date": "Fri, 27 Jan 2017 02:35:10 GMT",
+      "comments": {
+        "patch": [
+          {
+            "comment": "Added ExternalApiHelper class to be used in generating api documentation json files for external types."
+          },
+          {
+            "comment": "Added description for packages implementation."
+          },
+          {
+            "comment": "Added config folder with file to enable api-extractor on itself. rebuild project on previous build."
+          }
+        ]
+      }
+    },
+    {
       "version": "1.1.3",
@@ -7,0 +25,0 @@ "tag": "@microsoft/api-extractor_v1.1.3",

CHANGELOG.md

 # Change Log - @microsoft/api-extractor
 
-This log was last generated on Tue, 24 Jan 2017 01:36:35 GMT and should not be manually modified.
+This log was last generated on Fri, 27 Jan 2017 02:35:10 GMT and should not be manually modified.
 
+## 1.1.4
+Fri, 27 Jan 2017 02:35:10 GMT
+
+### Patches
+
+- Added ExternalApiHelper class to be used in generating api documentation json files for external types.
+- Added description for packages implementation.
+- Added config folder with file to enable api-extractor on itself. rebuild project on previous build.
+
 ## 1.1.3
@@ -6,0 +15,0 @@ Tue, 24 Jan 2017 01:36:35 GMT

lib/Analyzer.js

 "use strict";
 var ts = require("typescript");
 var ApiPackage_1 = require("./definitions/ApiPackage");
-var TypeScriptHelpers_1 = require("./TypeScriptHelpers");
 var DocItemLoader_1 = require("./DocItemLoader");
@@ -40,4 +39,3 @@ /**
         }
-        var rootFileSymbol = TypeScriptHelpers_1.default.getSymbolForDeclaration(rootFile);
-        this.package = new ApiPackage_1.default(this, rootFileSymbol);
+        this.package = new ApiPackage_1.default(this, rootFile);
     };
@@ -44,0 +42,0 @@ /**

lib/DebugRun.js

@@ -24,5 +24,5 @@ // NOTE: THIS SOURCE FILE IS FOR DEBUGGING PURPOSES ONLY.
         jsx: ts.JsxEmit.React,
-        rootDir: 'D:/GitRepos/sp-client/spfx-core/sp-codepart-base'
+        rootDir: './testInputs/example2'
     },
-    entryPointFile: 'D:/GitRepos/sp-client/spfx-core/sp-codepart-base/src/index.ts',
+    entryPointFile: './testInputs/example2/index.ts',
     otherFiles: []
@@ -29,0 +29,0 @@ });

lib/definitions/ApiDocumentation.js

@@ -8,2 +8,3 @@ /* tslint:disable:no-bitwise */
 var Tokenizer_1 = require("../Tokenizer");
+var ApiPackage_1 = require("./ApiPackage");
 /**
@@ -107,4 +108,6 @@ * An "API Tag" is a custom JSDoc tag which indicates whether an ApiItem definition
     ApiDocumentation.prototype._getJsDocs = function (apiItem) {
-        var sourceFile = apiItem.getDeclaration().getSourceFile();
-        var jsDoc = TypeScriptHelpers_1.default.getJsDocComments(apiItem.getDeclaration(), this.reportError);
+        if (!apiItem.jsdocNode) {
+            return '';
+        }
+        var jsDoc = TypeScriptHelpers_1.default.getJsDocComments(apiItem.jsdocNode, this.reportError);
         // Eliminate tags and then count the English letters.  Are there at least 10 letters of text?
@@ -250,2 +253,9 @@ // If not, we consider the definition to be "missingDocumentation".
         }
+        if (this.apiItem instanceof ApiPackage_1.default) {
+            if (apiTagCount > 0) {
+                var tag = '@' + ApiTag[this.apiTag].toLowerCase();
+                this.reportError("The " + tag + " tag is not allowed on the package, which is always public");
+            }
+            this.apiTag = ApiTag.Public;
+        }
         if (this.preapproved) {
@@ -252,0 +262,0 @@ if (this.apiTag !== ApiTag.Internal) {

lib/definitions/ApiEnum.js

@@ -24,3 +24,4 @@ "use strict";
                 declaration: memberDeclaration,
-                declarationSymbol: memberSymbol
+                declarationSymbol: memberSymbol,
+                jsdocNode: memberDeclaration
             };
@@ -27,0 +28,0 @@ _this.addMemberItem(new ApiEnumValue_1.default(memberOptions));

lib/definitions/ApiFunction.js

@@ -33,3 +33,4 @@ "use strict";
                     declaration: param,
-                    declarationSymbol: declarationSymbol
+                    declarationSymbol: declarationSymbol,
+                    jsdocNode: param
                 }, docComment));
@@ -36,0 +37,0 @@ }

lib/definitions/ApiItem.d.ts

@@ -8,5 +8,23 @@ import * as ts from 'typescript';
 export interface IApiItemOptions {
+    /**
+     * The associated Analyzer object for this ApiItem
+     */
     analyzer: Analyzer;
+    /**
+     * The declaration node for the main syntax item that this ApiItem is associated with.
+     */
     declaration: ts.Declaration;
+    /**
+     * The semantic information for the declaration.
+     */
     declarationSymbol: ts.Symbol;
+    /**
+     * The declaration node that contains the JSDoc comments for this ApiItem.
+     * In most cases this is the same as `declaration`, but for ApiPackage it will be
+     * a separate node under the root.
+     */
+    jsdocNode: ts.Node;
+    /**
+     * The symbol used to export this ApiItem from the ApiPackage.
+     */
     exportSymbol?: ts.Symbol;
@@ -38,2 +56,8 @@ }
     warnings: string[];
+    /**
+     * The declaration node that contains the JSDoc comments for this ApiItem.
+     * In most cases this is the same as `declaration`, but for ApiPackage it will be
+     * a separate node under the root.
+     */
+    jsdocNode: ts.Node;
     documentation: ApiDocumentation;
@@ -40,0 +64,0 @@ /**

lib/definitions/ApiItem.js

@@ -16,2 +16,3 @@ /* tslint:disable:no-bitwise */
         this.declaration = options.declaration;
+        this.jsdocNode = options.jsdocNode;
         this._errorNode = options.declaration;
@@ -18,0 +19,0 @@ this.warnings = [];

lib/definitions/ApiMember.js

@@ -60,3 +60,4 @@ "use strict";
                 declaration: propertyTypeDeclaration,
-                declarationSymbol: propertyTypeSymbol
+                declarationSymbol: propertyTypeSymbol,
+                jsdocNode: propertyTypeDeclaration
             };
@@ -63,0 +64,0 @@ _this.typeLiteral = new ApiStructuredType_1.default(typeLiteralOptions);

lib/definitions/ApiMethod.js

@@ -33,3 +33,4 @@ "use strict";
                     declaration: param,
-                    declarationSymbol: declarationSymbol
+                    declarationSymbol: declarationSymbol,
+                    jsdocNode: param
                 }, docComment));
@@ -36,0 +37,0 @@ }

lib/definitions/ApiPackage.d.ts

@@ -9,4 +9,5 @@ import * as ts from 'typescript';
 export default class ApiPackage extends ApiItemContainer {
-    constructor(analyzer: Analyzer, rootFileSymbol: ts.Symbol);
+    private static _getOptions(analyzer, rootFile);
+    constructor(analyzer: Analyzer, rootFile: ts.SourceFile);
     shouldHaveDocumentation(): boolean;
 }

lib/definitions/ApiPackage.js

@@ -13,2 +13,3 @@ /* tslint:disable:no-bitwise */
 var ApiItemContainer_1 = require("./ApiItemContainer");
+var TypeScriptHelpers_1 = require("../TypeScriptHelpers");
 /**
@@ -20,9 +21,5 @@ * This class is part of the ApiItem abstract syntax tree.  It represents the top-level
     __extends(ApiPackage, _super);
-    function ApiPackage(analyzer, rootFileSymbol) {
-        var _this = _super.call(this, {
-            analyzer: analyzer,
-            declaration: rootFileSymbol.declarations[0],
-            declarationSymbol: rootFileSymbol
-        }) || this;
-        var exportSymbols = _this.typeChecker.getExportsOfModule(rootFileSymbol);
+    function ApiPackage(analyzer, rootFile) {
+        var _this = _super.call(this, ApiPackage._getOptions(analyzer, rootFile)) || this;
+        var exportSymbols = _this.typeChecker.getExportsOfModule(_this.declarationSymbol);
         if (exportSymbols) {
@@ -42,2 +39,3 @@ for (var _i = 0, exportSymbols_1 = exportSymbols; _i < exportSymbols_1.length; _i++) {
                         declarationSymbol: followedSymbol,
+                        jsdocNode: declaration,
                         exportSymbol: exportSymbol
@@ -62,2 +60,25 @@ };
     }
+    ApiPackage._getOptions = function (analyzer, rootFile) {
+        var rootFileSymbol = TypeScriptHelpers_1.default.getSymbolForDeclaration(rootFile);
+        var statement;
+        var foundDescription = undefined;
+        for (var _i = 0, _a = rootFile.statements; _i < _a.length; _i++) {
+            var statementNode = _a[_i];
+            if (statementNode.kind === ts.SyntaxKind.VariableStatement) {
+                statement = statementNode;
+                for (var _b = 0, _c = statement.declarationList.declarations; _b < _c.length; _b++) {
+                    var statementDeclaration = _c[_b];
+                    if (statementDeclaration.name.getText() === 'packageDescription') {
+                        foundDescription = statement;
+                    }
+                }
+            }
+        }
+        return {
+            analyzer: analyzer,
+            declaration: rootFileSymbol.declarations[0],
+            declarationSymbol: rootFileSymbol,
+            jsdocNode: foundDescription
+        };
+    };
     ApiPackage.prototype.shouldHaveDocumentation = function () {
@@ -64,0 +85,0 @@ // We don't write JSDoc for the ApiPackage object

lib/definitions/ApiStructuredType.js

@@ -161,3 +161,4 @@ /* tslint:disable:no-bitwise */
             declaration: memberDeclaration,
-            declarationSymbol: memberSymbol
+            declarationSymbol: memberSymbol,
+            jsdocNode: memberDeclaration
         };
@@ -164,0 +165,0 @@ if (memberSymbol.flags & (ts.SymbolFlags.Method |

lib/example1-output.ts

@@ -34,1 +34,2 @@ // @public
 
+// (No packageDescription for this package)

lib/example2-output.json

 {
   "kind": "package",
+  "summary": [
+    {
+      "kind": "textDocElement",
+      "value": "Here is some documentation for example2."
+    }
+  ],
+  "remarks": [
+    {
+      "kind": "textDocElement",
+      "value": "These are additional remarks that may be too long for the summary. They should appear in the remarks of the json generated file for this package."
+    }
+  ],
   "exports": {
@@ -4,0 +16,0 @@ "inheritCorrectlyButNotFound": {

lib/generators/ApiFileGenerator.d.ts

@@ -32,4 +32,4 @@ import Analyzer from '../Analyzer';
      * Generates the report and writes it to disk.
-     * @param reportFilename   The output filename
-     * @param analyzer         An Analyzer object representing the input project.
+     * @param reportFilename - The output filename
+     * @param analyzer       - An Analyzer object representing the input project.
      */
@@ -36,0 +36,0 @@ writeApiFile(reportFilename: string, analyzer: Analyzer): void;

lib/generators/ApiFileGenerator.js

@@ -10,2 +10,3 @@ "use strict";
 var ApiItemVisitor_1 = require("../ApiItemVisitor");
+var ApiPackage_1 = require("../definitions/ApiPackage");
 var IndentedWriter_1 = require("../IndentedWriter");
@@ -44,4 +45,4 @@ var ApiDocumentation_1 = require("../definitions/ApiDocumentation");
      * Generates the report and writes it to disk.
-     * @param reportFilename   The output filename
-     * @param analyzer         An Analyzer object representing the input project.
+     * @param reportFilename - The output filename
+     * @param analyzer       - An Analyzer object representing the input project.
      */
@@ -127,34 +128,39 @@ ApiFileGenerator.prototype.writeApiFile = function (reportFilename, analyzer) {
         var lines = apiItem.warnings.map(function (x) { return 'WARNING: ' + x; });
-        var footer = '';
-        switch (apiItem.documentation.apiTag) {
-            case ApiDocumentation_1.ApiTag.Internal:
-                footer += '@internal';
-                break;
-            case ApiDocumentation_1.ApiTag.Alpha:
-                footer += '@alpha';
-                break;
-            case ApiDocumentation_1.ApiTag.Beta:
-                footer += '@beta';
-                break;
-            case ApiDocumentation_1.ApiTag.Public:
-                footer += '@public';
-                break;
+        if (apiItem instanceof ApiPackage_1.default && !apiItem.documentation.summary.length) {
+            lines.push('(No packageDescription for this package)');
         }
-        // deprecatedMessage is initialized by default,
-        // this ensures it has contents before adding '@deprecated'
-        if (apiItem.documentation.deprecatedMessage.length > 0) {
-            if (footer) {
-                footer += ' ';
+        else {
+            var footer = '';
+            switch (apiItem.documentation.apiTag) {
+                case ApiDocumentation_1.ApiTag.Internal:
+                    footer += '@internal';
+                    break;
+                case ApiDocumentation_1.ApiTag.Alpha:
+                    footer += '@alpha';
+                    break;
+                case ApiDocumentation_1.ApiTag.Beta:
+                    footer += '@beta';
+                    break;
+                case ApiDocumentation_1.ApiTag.Public:
+                    footer += '@public';
+                    break;
             }
-            footer += '@deprecated';
-        }
-        if (apiItem.documentation.isMissing) {
+            // deprecatedMessage is initialized by default,
+            // this ensures it has contents before adding '@deprecated'
+            if (apiItem.documentation.deprecatedMessage.length > 0) {
+                if (footer) {
+                    footer += ' ';
+                }
+                footer += '@deprecated';
+            }
+            if (apiItem.documentation.isMissing) {
+                if (footer) {
+                    footer += ' ';
+                }
+                footer += '(undocumented)';
+            }
             if (footer) {
-                footer += ' ';
+                lines.push(footer);
             }
-            footer += '(undocumented)';
         }
-        if (footer) {
-            lines.push(footer);
-        }
         if (lines.length) {
@@ -161,0 +167,0 @@ // Write the lines prefixed by slashes.  If there  are multiple lines, add "//" to each line

lib/generators/ApiJsonGenerator.js

@@ -128,2 +128,4 @@ "use strict";
         refObject['kind'] = ApiJsonGenerator._KIND_PACKAGE; /* tslint:disable-line:no-string-literal */
+        refObject['summary'] = apiPackage.documentation.summary; /* tslint:disable-line:no-string-literal */
+        refObject['remarks'] = apiPackage.documentation.remarks; /* tslint:disable-line:no-string-literal */
         var membersNode = {};
@@ -130,0 +132,0 @@ refObject[ApiJsonGenerator._EXPORTS_KEY] = membersNode;

lib/index.d.ts

 export { default as Analyzer, IApiAnalyzerOptions, ApiErrorHandler } from './Analyzer';
 export { default as ApiFileGenerator } from './generators/ApiFileGenerator';
 export { default as ApiJsonGenerator } from './generators/ApiJsonGenerator';
+export { default as ExternalApiHelper } from './ExternalApiHelper';

lib/index.js

@@ -8,3 +8,5 @@ "use strict";
 exports.ApiJsonGenerator = ApiJsonGenerator_1.default;
+var ExternalApiHelper_1 = require("./ExternalApiHelper");
+exports.ExternalApiHelper = ExternalApiHelper_1.default;
 
 //# sourceMappingURL=index.js.map

lib/PrettyPrinter.js

@@ -15,18 +15,24 @@ /* tslint:disable:no-bitwise */
         if (indent === void 0) { indent = ''; }
-        if (node.kind === ts.SyntaxKind.FromKeyword) {
-            console.log('**');
-        }
         var kindName = ts.SyntaxKind[node.kind];
-        var trimmedText = node.getText()
-            .replace(/[\r\n]/g, ' ')
-            .replace(/\s+/g, ' ')
-            .trim();
-        if (trimmedText.length > 100) {
-            trimmedText = trimmedText.substr(0, 97) + '...';
+        var trimmedText;
+        try {
+            trimmedText = node.getText()
+                .replace(/[\r\n]/g, ' ')
+                .replace(/\s+/g, ' ')
+                .trim();
+            if (trimmedText.length > 100) {
+                trimmedText = trimmedText.substr(0, 97) + '...';
+            }
         }
-        console.log("" + indent + kindName + ": [" + trimmedText + "]");
-        for (var _i = 0, _a = node.getChildren(); _i < _a.length; _i++) {
-            var childNode = _a[_i];
-            PrettyPrinter.dumpTree(childNode, indent + '  ');
+        catch (e) {
+            trimmedText = '(error getting text)';
         }
+        try {
+            for (var _i = 0, _a = node.getChildren(); _i < _a.length; _i++) {
+                var childNode = _a[_i];
+                PrettyPrinter.dumpTree(childNode, indent + '  ');
+            }
+        }
+        catch (e) {
+        }
     };
@@ -33,0 +39,0 @@ /**

lib/schemas/api-json-schema.json

@@ -525,2 +525,8 @@ {
     },
+    "summary": {
+          "$ref": "#/definitions/docElementCollection"
+    },
+    "remarks": {
+          "$ref": "#/definitions/docElementCollection"
+    },
     "exports": {
@@ -527,0 +533,0 @@ "description": "The exported definitions for this API package",

package.json

 {
   "name": "@microsoft/api-extractor",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "Validatation, documentation, and auditing for the exported API of a TypeScript package",
@@ -5,0 +5,0 @@ "main": "lib/index.js",

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

Improved metrics

Total package byte prevSize

508150

increased by3.62%

Number of package files

143

increased by2.14%

Lines of code

5972

increased by3.34%

Worsened metrics

Number of low supply chain risk alerts

7

increased by16.67%

No dependency changes