@microsoft/api-extractor - npm Package Compare versions

Comparing version 2.0.10 to 2.1.0

CHANGELOG.json

@@ -5,2 +5,14 @@ {
     {
+      "version": "2.1.0",
+      "tag": "@microsoft/api-extractor_v2.1.0",
+      "date": "Tue, 20 Jun 2017 23:21:16 GMT",
+      "comments": {
+        "minor": [
+          {
+            "comment": "Add two new features: An error is reported if a top-level definition is missing its release tag. The constructor summary will now be autogenerated if omitted."
+          }
+        ]
+      }
+    },
+    {
       "version": "2.0.10",
@@ -12,3 +24,3 @@ "tag": "@microsoft/api-extractor_v2.0.10",
           {
-            "comment": "Improved the wording of many error messages"
+            "comment": "Improve the wording of many error messages"
           },
@@ -19,3 +31,3 @@ {
           {
-            "comment": "API Extractor now issues warnings for @internal definitions that are not prefixed with an underscore"
+            "comment": "Issue warnings for @internal definitions that are not prefixed with an underscore"
           }
@@ -22,0 +34,0 @@ ]

CHANGELOG.md

 # Change Log - @microsoft/api-extractor
 
-This log was last generated on Tue, 20 Jun 2017 01:04:54 GMT and should not be manually modified.
+This log was last generated on Tue, 20 Jun 2017 23:21:16 GMT and should not be manually modified.
 
+## 2.1.0
+Tue, 20 Jun 2017 23:21:16 GMT
+
+### Minor changes
+
+- Add two new features: An error is reported if a top-level definition is missing its release tag. The constructor summary will now be autogenerated if omitted.
+
 ## 2.0.10
@@ -10,5 +17,5 @@ Tue, 20 Jun 2017 01:04:54 GMT
 
-- Improved the wording of many error messages
+- Improve the wording of many error messages
 - Fix a bug with parsing of @link tags
-- API Extractor now issues warnings for @internal definitions that are not prefixed with an underscore
+- Issue warnings for @internal definitions that are not prefixed with an underscore
 
@@ -15,0 +22,0 @@ ## 2.0.9

lib/ApiDefinitionReference.d.ts

@@ -92,4 +92,5 @@ /**
      * and deconstructs it into an IApiDefinitionReference interface object.
+     * @returns the ApiDefinitionReference, or undefined if an error was reported.
      */
-    static createFromString(apiReferenceExpr: string, reportError: (message: string) => void): ApiDefinitionReference;
+    static createFromString(apiReferenceExpr: string, reportError: (message: string) => void): ApiDefinitionReference | undefined;
     /**
@@ -96,0 +97,0 @@ * For a scoped NPM package name this separates the scope and package parts.  For example:

lib/ApiDefinitionReference.js

@@ -23,2 +23,3 @@ "use strict";
      * and deconstructs it into an IApiDefinitionReference interface object.
+     * @returns the ApiDefinitionReference, or undefined if an error was reported.
      */
@@ -28,3 +29,3 @@ ApiDefinitionReference.createFromString = function (apiReferenceExpr, reportError) {
             reportError('An API item reference must use the notation: "@scopeName/packageName:exportName.memberName"');
-            return;
+            return undefined;
         }
@@ -54,7 +55,9 @@ var apiDefRefParts = {
             // the export name is required
-            throw reportError("The API item reference contains an invalid \"exportName.memberName\""
+            reportError("The API item reference contains an invalid \"exportName.memberName\""
                 + (" expression: \"" + apiReferenceExpr + "\""));
+            return undefined;
         }
         if (!apiReferenceExpr.match(ApiDefinitionReference._exportRegEx)) {
-            throw reportError("The API item reference contains invalid characters: \"" + apiReferenceExpr + "\"");
+            reportError("The API item reference contains invalid characters: \"" + apiReferenceExpr + "\"");
+            return undefined;
         }
@@ -61,0 +64,0 @@ return ApiDefinitionReference.createFromParts(apiDefRefParts);

lib/definitions/ApiDocumentation.d.ts

@@ -148,3 +148,9 @@ /// <reference types="es6-collections" />
     extractor: Extractor;
-    reportError: (message: string) => void;
+    /**
+     * True if any errors were encountered while parsing the AEDoc tokens.
+     * This is used to suppress other "collateral damage" errors, e.g. if "@public" was
+     * misspelled then we shouldn't also complain that the "@public" tag is missing.
+     */
+    failedToParse: boolean;
+    readonly reportError: (message: string) => void;
     constructor(docComment: string, referenceResolver: IReferenceResolver, extractor: Extractor, errorLogger: (message: string) => void, warnings: string[]);
@@ -159,5 +165,5 @@ /**
     /**
-   * A processing of linkDocElements that refer to an ApiDefinitionReference. This method
-   * ensures that the reference is to an API item that is not 'Internal'.
-   */
+     * A processing of linkDocElements that refer to an ApiDefinitionReference. This method
+     * ensures that the reference is to an API item that is not 'Internal'.
+     */
     private _completeLinks();
@@ -164,0 +170,0 @@ /**

lib/definitions/ApiDocumentation.js

@@ -46,2 +46,7 @@ /* tslint:disable:no-bitwise */
     function ApiDocumentation(docComment, referenceResolver, extractor, errorLogger, warnings) {
+        var _this = this;
+        this.reportError = function (message) {
+            errorLogger(message);
+            _this.failedToParse = true;
+        };
         this.originalAedoc = docComment;
@@ -228,5 +233,5 @@ this.referenceResolver = referenceResolver;
     /**
-   * A processing of linkDocElements that refer to an ApiDefinitionReference. This method
-   * ensures that the reference is to an API item that is not 'Internal'.
-   */
+     * A processing of linkDocElements that refer to an ApiDefinitionReference. This method
+     * ensures that the reference is to an API item that is not 'Internal'.
+     */
     ApiDocumentation.prototype._completeLinks = function () {
@@ -233,0 +238,0 @@ while (this.incompleteLinks.length) {

lib/definitions/ApiItem.d.ts

 import * as ts from 'typescript';
 import Extractor from '../Extractor';
 import ApiDocumentation from './ApiDocumentation';
+import ApiItemContainer from './ApiItemContainer';
 /**
@@ -152,2 +153,5 @@ * Indicates the type of definition represented by a ApiItem object.
     jsdocNode: ts.Node;
+    /**
+     * The parsed AEDoc comment for this item.
+     */
     documentation: ApiDocumentation;
@@ -193,4 +197,9 @@ /**
     private _state;
+    private _parentContainer;
     constructor(options: IApiItemOptions);
     /**
+     * Called by ApiItemContainer.addMemberItem().  Other code should NOT call this method.
+     */
+    notifyAddedToContainer(parentContainer: ApiItemContainer): void;
+    /**
      * Called after the constructor to finish the analysis.
@@ -217,2 +226,6 @@ */
     /**
+     * The ApiItemContainer that this member belongs to, or undefined if there is none.
+     */
+    readonly parentContainer: ApiItemContainer | undefined;
+    /**
      * This traverses any type aliases to find the original place where an item was defined.
@@ -235,5 +248,5 @@ * For example, suppose a class is defined as "export default class MyClass { }"
     /**
-      * Adds a warning to the ApiItem.warnings list.  These warnings will be emtted in the API file
-      * produced by ApiFileGenerator.
-      */
+     * Adds a warning to the ApiItem.warnings list.  These warnings will be emtted in the API file
+     * produced by ApiFileGenerator.
+     */
     protected reportWarning(message: string): void;
@@ -240,0 +253,0 @@ /**

lib/definitions/ApiItem.js

@@ -146,2 +146,12 @@ /* tslint:disable:no-bitwise */
     /**
+     * Called by ApiItemContainer.addMemberItem().  Other code should NOT call this method.
+     */
+    ApiItem.prototype.notifyAddedToContainer = function (parentContainer) {
+        if (this._parentContainer) {
+            // This would indicate a program bug
+            throw new Error('The API item has already been added to another container: ' + this._parentContainer.name);
+        }
+        this._parentContainer = parentContainer;
+    };
+    /**
      * Called after the constructor to finish the analysis.
@@ -175,2 +185,12 @@ */
     };
+    Object.defineProperty(ApiItem.prototype, "parentContainer", {
+        /**
+         * The ApiItemContainer that this member belongs to, or undefined if there is none.
+         */
+        get: function () {
+            return this._parentContainer;
+        },
+        enumerable: true,
+        configurable: true
+    });
     /**
@@ -209,5 +229,5 @@ * This traverses any type aliases to find the original place where an item was defined.
     /**
-      * Adds a warning to the ApiItem.warnings list.  These warnings will be emtted in the API file
-      * produced by ApiFileGenerator.
-      */
+     * Adds a warning to the ApiItem.warnings list.  These warnings will be emtted in the API file
+     * produced by ApiFileGenerator.
+     */
     ApiItem.prototype.reportWarning = function (message) {
@@ -259,2 +279,15 @@ this.warnings.push(message);
         }
+        // Is it missing a release tag?
+        if (this.documentation.releaseTag === ApiDocumentation_1.ReleaseTag.None) {
+            // Only warn about top-level exports
+            if (this.parentContainer && this.parentContainer.kind === ApiItemKind.Package) {
+                // Don't warn about items that failed to parse.
+                if (!this.documentation.failedToParse) {
+                    // If there is no release tag, and this is a top-level export of the package, then
+                    // report an error
+                    this.reportError("A release tag (@alpha, @beta, @public, @internal) must be specified"
+                        + (" for " + this.name));
+                }
+            }
+        }
     };
@@ -261,0 +294,0 @@ /**

lib/definitions/ApiItemContainer.js

@@ -54,2 +54,3 @@ "use strict";
             this._memberItems.set(apiItem.name, apiItem);
+            apiItem.notifyAddedToContainer(this);
         }
@@ -56,0 +57,0 @@ };

lib/definitions/ApiMethod.d.ts

@@ -12,5 +12,11 @@ import { IApiItemOptions } from './ApiItem';
 export default class ApiMethod extends ApiMember {
-    returnType: string;
-    params: ApiParameter[];
+    readonly returnType: string;
+    readonly params: ApiParameter[];
+    private readonly _isConstructor;
     constructor(options: IApiItemOptions);
+    /**
+     * Returns true if this member represents a class constructor.
+     */
+    readonly isConstructor: boolean;
+    protected onCompleteInitialization(): void;
 }

lib/definitions/ApiMethod.js

@@ -13,2 +13,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+var ts = require("typescript");
 var ApiItem_1 = require("./ApiItem");
@@ -18,2 +19,3 @@ var ApiMember_1 = require("./ApiMember");
 var TypeScriptHelpers_1 = require("../TypeScriptHelpers");
+var ApiDefinitionReference_1 = require("../ApiDefinitionReference");
 /**
@@ -48,4 +50,6 @@ * This class is part of the ApiItem abstract syntax tree. It represents functions that are members of
         }
+        // tslint:disable-next-line:no-bitwise
+        _this._isConstructor = (options.declarationSymbol.flags & ts.SymbolFlags.Constructor) !== 0;
         // Return type
-        if (!(_this.name === '__constructor')) {
+        if (!_this.isConstructor) {
             if (methodDeclaration.type) {
@@ -61,2 +65,41 @@ _this.returnType = methodDeclaration.type.getText();
     }
+    Object.defineProperty(ApiMethod.prototype, "isConstructor", {
+        /**
+         * Returns true if this member represents a class constructor.
+         */
+        get: function () {
+            return this._isConstructor;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    ApiMethod.prototype.onCompleteInitialization = function () {
+        _super.prototype.onCompleteInitialization.call(this);
+        // If this is a class constructor, and if the documentation summary was omitted, then
+        // we fill in a default summary versus flagging it as "undocumented".
+        // Generally class constructors have uninteresting documentation.
+        if (this.isConstructor) {
+            if (this.documentation.summary.length === 0) {
+                this.documentation.summary.push({
+                    kind: 'textDocElement',
+                    value: 'Constructs a new instance of the '
+                });
+                var scopedPackageName = ApiDefinitionReference_1.default
+                    .parseScopedPackageName(this.extractor.package.name);
+                this.documentation.summary.push({
+                    kind: 'linkDocElement',
+                    referenceType: 'code',
+                    scopeName: scopedPackageName.scope,
+                    packageName: scopedPackageName.package,
+                    exportName: this.parentContainer.name,
+                    value: this.parentContainer.name
+                });
+                this.documentation.summary.push({
+                    kind: 'textDocElement',
+                    value: ' class'
+                });
+            }
+            this.needsDocumentation = false;
+        }
+    };
     return ApiMethod;
@@ -63,0 +106,0 @@ }(ApiMember_1.default));

lib/example1-output.api.ts

@@ -0,1 +1,3 @@
+// WARNING: The underscore prefix ("_") should only be used with definitions that are explicitly marked as @internal
+// @public
 class ___proto__ {
@@ -19,3 +21,3 @@ // (undocumented)
 
-// (undocumented)
+// @public (undocumented)
 class A extends __proto__, implements hasOwnProperty {
@@ -60,3 +62,3 @@ // (undocumented)
 
-// (undocumented)
+// @public (undocumented)
 interface hasOwnProperty {
@@ -67,3 +69,3 @@ // (undocumented)
 
-// (undocumented)
+// @public (undocumented)
 class MyClass {
@@ -78,3 +80,3 @@ // (undocumented)
 
-// (undocumented)
+// @public (undocumented)
 export function publicFunction(param: number): string;
@@ -81,0 +83,0 @@

lib/example2-output.api.ts

 // WARNING: Unable to find a documentation file ("es6-collections.api.json") for the referenced package
+// @public
 interface IExternalPackageLookupInheritDoc {
@@ -6,15 +7,19 @@ }
 // WARNING: __constructor has incomplete type information
+// @public
 class IncompleteTypeConstructor {
 }
 
+// @public
 enum inheritDisplayMode {
 }
 
+// @public
 enum inheritDisplayModeError {
 }
 
+// @public
 enum inheritDisplayModeErrorDeprecated {
 }
 
-// @deprecated
+// @public @deprecated
 enum inheritDisplayModeNoErrorDeprecated {
@@ -28,3 +33,2 @@ }
 class MyDocumentedClass {
-  // (undocumented)
   constructor();
@@ -53,5 +57,7 @@ // WARNING: The name "$unallowedName" contains unsupported characters; API names should use only letters, numbers, and underscores
 // WARNING: Unable to find referenced export "@microsoft/sp-core-library:Display""
+// @public
 enum packageLocatedButExportNotFound {
 }
 
+// @public
 enum TestMissingCommentStar {
@@ -58,0 +64,0 @@ }

lib/example2-output.json

@@ -158,3 +158,20 @@ {
           "deprecatedMessage": [],
-          "summary": [],
+          "summary": [
+            {
+              "kind": "textDocElement",
+              "value": "Constructs a new instance of the "
+            },
+            {
+              "kind": "linkDocElement",
+              "referenceType": "code",
+              "scopeName": "",
+              "packageName": "example2",
+              "exportName": "MyDocumentedClass",
+              "value": "MyDocumentedClass"
+            },
+            {
+              "kind": "textDocElement",
+              "value": " class"
+            }
+          ],
           "remarks": []
@@ -161,0 +178,0 @@ },

lib/example3-output.api.ts

@@ -5,2 +5,3 @@ // @internal
 
+// @public
 enum inheritEnumValues {
@@ -11,10 +12,11 @@ index_one = 1,
 
-// (undocumented)
+// @public (undocumented)
 enum inheritLocalCircularDependencyOne {
 }
 
-// (undocumented)
+// @public (undocumented)
 enum inheritLocalCircularDependencyTwo {
 }
 
+// @public
 enum inheritLocalOptionOne {
@@ -24,4 +26,6 @@ }
 // WARNING: Unable to find referenced member "MyClass.methodWithTwoParams"
+// @public
 export function inheritLocalOptionTwoFunction(): void;
 
+// @public
 interface IStructuredTypeInherit {
@@ -31,2 +35,3 @@ thisIsTypeLiteral: [{name: string, age: number}];
 
+// @public
 interface IStructuredTypeSource {
@@ -39,2 +44,3 @@ thisIsTypeLiteral: {
 
+// @public
 class jsonResolutionClass {
@@ -44,4 +50,6 @@ public jsonResolutionMethod(): boolean;
 
+// @public
 export function jsonResolutionFunction(): boolean;
 
+// @public
 class MyClass {
@@ -54,2 +62,3 @@ }
 
+// @public
 enum sourceEnumValuesDoc {
@@ -60,4 +69,5 @@ one = 1,
 
+// @public
 enum testingLinks {
 }
 

lib/generators/test/ApiFileGenerator.test.js

@@ -22,2 +22,5 @@ /// <reference types="mocha" />
 }
+function assertCapturedErrors(expectedMessages) {
+    chai_1.assert.deepEqual(capturedErrors.map(function (x) { return x.message; }), expectedMessages, 'The captured errors did not match the expected output.');
+}
 describe('ApiFileGenerator tests', function () {
@@ -50,6 +53,6 @@ this.timeout(10000);
              */
-            chai_1.assert.equal(capturedErrors.length, 2);
-            chai_1.assert.equal(capturedErrors[0].message, 'The JSDoc tag "@badAedocTag" is not supported by AEDoc');
-            chai_1.assert.equal(capturedErrors[1].message, 'Unexpected text in AEDoc comment: '
-                + '"(Error #1 is the bad tag) Text can no..."');
+            assertCapturedErrors([
+                'The JSDoc tag "@badAedocTag" is not supported by AEDoc',
+                'Unexpected text in AEDoc comment: "(Error #1 is the bad tag) Text can no..."'
+            ]);
         });
@@ -56,0 +59,0 @@ it('Example 2', function () {

lib/test/ApiDefinitionReference.test.js

@@ -11,2 +11,8 @@ /// <reference types="mocha" />
 }
+function clearCapturedErrors() {
+    capturedErrors = [];
+}
+function assertCapturedErrors(expectedMessages) {
+    chai_1.assert.deepEqual(capturedErrors.map(function (x) { return x.message; }), expectedMessages, 'The captured errors did not match the expected output.');
+}
 describe('ApiDocumentation tests', function () {
@@ -42,13 +48,8 @@ this.timeout(10000);
         it('_parseApiReferenceExpression() without scope name and invalid memberName', function () {
+            clearCapturedErrors();
             // This won't raise an error (based on our current decision to only show warnings in the *.api.ts
             // files if we can't find a reference)
             apiReferenceExpr = 'sp-core-library:Guid:equals';
-            var caughtError = false;
-            try {
-                actual = ApiDefinitionReference_1.default.createFromString(apiReferenceExpr, console.log);
-            }
-            catch (error) {
-                caughtError = true;
-            }
-            chai_1.assert.equal(caughtError, true);
+            actual = ApiDefinitionReference_1.default.createFromString(apiReferenceExpr, console.log);
+            assertCapturedErrors([]);
         });
@@ -55,0 +56,0 @@ });

package.json

 {
   "name": "@microsoft/api-extractor",
-  "version": "2.0.10",
+  "version": "2.1.0",
   "description": "Validate, document, and review the exported API for a TypeScript library",
@@ -5,0 +5,0 @@ "keywords": [

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

775024

increased by1.72%

Lines of code

9712

increased by1.7%

No dependency changes