@microsoft/api-extractor - npm Package Compare versions

Comparing version 1.1.6 to 1.1.7

CHANGELOG.json

@@ -5,2 +5,14 @@ {
     {
+      "version": "1.1.7",
+      "tag": "@microsoft/api-extractor_v1.1.7",
+      "date": "Thu, 02 Feb 2017 14:05:53 GMT",
+      "comments": {
+        "patch": [
+          {
+            "comment": "Refactored ApiDocumentation creation to resolve references method."
+          }
+        ]
+      }
+    },
+    {
       "version": "1.1.6",
@@ -7,0 +19,0 @@ "tag": "@microsoft/api-extractor_v1.1.6",

CHANGELOG.md

 # Change Log - @microsoft/api-extractor
 
-This log was last generated on Wed, 01 Feb 2017 20:09:30 GMT and should not be manually modified.
+This log was last generated on Thu, 02 Feb 2017 14:05:53 GMT and should not be manually modified.
 
+## 1.1.7
+Thu, 02 Feb 2017 14:05:53 GMT
+
+### Patches
+
+- Refactored ApiDocumentation creation to resolve references method.
+
 ## 1.1.6
@@ -6,0 +13,0 @@ Wed, 01 Feb 2017 20:09:30 GMT

lib/ApiItemVisitor.js

@@ -7,3 +7,2 @@ "use strict";
 var ApiStructuredType_1 = require("./definitions/ApiStructuredType");
-var ApiMember_1 = require("./definitions/ApiMember");
 var ApiMethod_1 = require("./definitions/ApiMethod");
@@ -43,5 +42,2 @@ var ApiProperty_1 = require("./definitions/ApiProperty");
         }
-        else if (apiItem instanceof ApiMember_1.default) {
-            this.visitApiMember(apiItem, refObject);
-        }
         else {
@@ -48,0 +44,0 @@ throw new Error('Not implemented');

lib/DebugRun.js

@@ -15,3 +15,4 @@ // NOTE: THIS SOURCE FILE IS FOR DEBUGGING PURPOSES ONLY.
     jsx: ts.JsxEmit.React,
-    rootDir: './testInputs/example2'
+    rootDir: './testInputs/example2',
+    typeRoots: ['./'] // We need to ignore @types in these tests
 };
@@ -18,0 +19,0 @@ var extractor = new Extractor_1.default({

lib/definitions/ApiDocumentation.d.ts

@@ -8,2 +8,3 @@ /// <reference types="es6-collections" />
 import Tokenizer from '../Tokenizer';
+import Extractor from '../Extractor';
 /**
@@ -138,2 +139,7 @@ * An "API Tag" is a custom JSDoc tag which indicates whether an ApiItem definition
     docItemLoader: DocItemLoader;
+    /**
+     * We need the extractor to access the package that this ApiItem
+     * belongs to in order to resolve references.
+     */
+    extractor: Extractor;
     reportError: (message: string) => void;
@@ -151,3 +157,3 @@ /**
     private static parseScopedPackageName(scopedName);
-    constructor(apiItem: ApiItem, docItemLoader: DocItemLoader, errorLogger: (message: string) => void);
+    constructor(apiItem: ApiItem, docItemLoader: DocItemLoader, extractor: Extractor, errorLogger: (message: string) => void);
     protected _getJsDocs(apiItem: ApiItem): string;
@@ -154,0 +160,0 @@ protected _parseDocs(): void;

lib/definitions/ApiDocumentation.js

@@ -44,5 +44,6 @@ /* tslint:disable:no-bitwise */
 var ApiDocumentation = (function () {
-    function ApiDocumentation(apiItem, docItemLoader, errorLogger) {
+    function ApiDocumentation(apiItem, docItemLoader, extractor, errorLogger) {
         this.apiItem = apiItem;
         this.docItemLoader = docItemLoader;
+        this.extractor = extractor;
         this.reportError = errorLogger;
@@ -49,0 +50,0 @@ this.docComment = this._getJsDocs(apiItem);

lib/definitions/ApiFunction.js

@@ -29,4 +29,2 @@ "use strict";
                 var declarationSymbol = TypeScriptHelpers_1.default.tryGetSymbolForDeclaration(param);
-                var docComment = declarationSymbol && _this.documentation && _this.documentation.paramDocs ?
-                    _this.documentation.paramDocs.get(declarationSymbol.name) : '';
                 _this.params.push(new ApiParameter_1.default({
@@ -37,3 +35,3 @@ extractor: _this.extractor,
                     jsdocNode: param
-                }, docComment));
+                }));
             }
@@ -40,0 +38,0 @@ }

lib/definitions/ApiItem.d.ts

@@ -137,2 +137,7 @@ import * as ts from 'typescript';
     private _errorNode;
+    /**
+     * The state of this ApiItems references. These references could include \@inheritdoc references
+     * or type references.
+     */
+    private _state;
     constructor(options: IApiItemOptions);
@@ -178,3 +183,18 @@ /**
     protected reportWarning(message: string): void;
+    /**
+     * This function assumes all references from this ApiItem have been resolved and we can now safely create
+     * the documentation.
+     */
+    protected onResolveReferences(): void;
+    /**
+     * This function is a second stage that happens after Extractor.analyze() calls ApiItem constructor to build up
+     * the abstract syntax tree. In this second stage, we are creating the documentation for each ApiItem.
+     *
+     * This function makes sure we create the documentation for each ApiItem in the correct order.
+     * In the event that a circular dependency occurs, an error is reported. For example, if ApiItemOne has
+     * an \@inheritdoc referencing ApiItemTwo, and ApiItemTwo has an \@inheritdoc refercing ApiItemOne then
+     * we have a circular dependency and an error will be reported.
+     */
+    resolveReferences(): void;
 }
 export default ApiItem;

lib/definitions/ApiItem.js

@@ -53,2 +53,23 @@ /* tslint:disable:no-bitwise */
 /**
+ * The state of resolving the ApiItem's doc comment references inside a recursive call to ApiItem.resolveReferences().
+ */
+var ResolveState;
+(function (ResolveState) {
+    /**
+     * The references of this ApiItem have not begun to be resolved.
+     */
+    ResolveState[ResolveState["Unresolved"] = 0] = "Unresolved";
+    /**
+     * The refernces of this ApiItem are in the process of being resolved.
+     * If we encounter this state again during resolution, a circular dependency is
+     * has occured.
+     */
+    ResolveState[ResolveState["Resolving"] = 1] = "Resolving";
+    /**
+     * The references of this ApiItem have all been resolved and the documentation can
+     * now safely be created.
+     */
+    ResolveState[ResolveState["Resolved"] = 2] = "Resolved";
+})(ResolveState || (ResolveState = {}));
+/**
  * ApiItem is an abstract base that represents TypeScript API definitions such as classes,
@@ -65,2 +86,3 @@ * interfaces, enums, properties, functions, and variables.  Rather than directly using the
         this._errorNode = options.declaration;
+        this._state = ResolveState.Unresolved;
         this.warnings = [];
@@ -72,3 +94,2 @@ this.extractor = options.extractor;
         this.typeChecker = this.extractor.typeChecker;
-        this.documentation = new ApiDocumentation_1.default(this, options.extractor.docItemLoader, this.reportError);
     }
@@ -137,2 +158,35 @@ /**
     };
+    /**
+     * This function assumes all references from this ApiItem have been resolved and we can now safely create
+     * the documentation.
+     */
+    ApiItem.prototype.onResolveReferences = function () {
+        this.documentation = new ApiDocumentation_1.default(this, this.extractor.docItemLoader, this.extractor, this.reportError);
+        // TODO: this.collectTypeReferences(this); 
+    };
+    /**
+     * This function is a second stage that happens after Extractor.analyze() calls ApiItem constructor to build up
+     * the abstract syntax tree. In this second stage, we are creating the documentation for each ApiItem.
+     *
+     * This function makes sure we create the documentation for each ApiItem in the correct order.
+     * In the event that a circular dependency occurs, an error is reported. For example, if ApiItemOne has
+     * an \@inheritdoc referencing ApiItemTwo, and ApiItemTwo has an \@inheritdoc refercing ApiItemOne then
+     * we have a circular dependency and an error will be reported.
+     */
+    ApiItem.prototype.resolveReferences = function () {
+        switch (this._state) {
+            case ResolveState.Resolved:
+                return;
+            case ResolveState.Unresolved:
+                this._state = ResolveState.Resolving;
+                this.onResolveReferences();
+                this._state = ResolveState.Resolved;
+                return;
+            case ResolveState.Resolving:
+                this.reportError('circular reference');
+                return;
+            default:
+                throw new Error('ApiItem state is invalid');
+        }
+    };
     return ApiItem;
@@ -139,0 +193,0 @@ }());

lib/definitions/ApiItemContainer.d.ts

@@ -7,3 +7,3 @@ import ApiItem, { IApiItemOptions } from './ApiItem';
 declare abstract class ApiItemContainer extends ApiItem {
-    protected memberItems: ApiItem[];
+    memberItems: ApiItem[];
     constructor(options: IApiItemOptions);
@@ -18,3 +18,7 @@ /**
     protected addMemberItem(apiItem: ApiItem): void;
+    /**
+     * {@inheritdoc ApiItem.onResolveReferences }
+     */
+    protected onResolveReferences(): void;
 }
 export default ApiItemContainer;

lib/definitions/ApiItemContainer.js

@@ -32,2 +32,11 @@ "use strict";
     };
+    /**
+     * {@inheritdoc ApiItem.onResolveReferences }
+     */
+    ApiItemContainer.prototype.onResolveReferences = function () {
+        _super.prototype.onResolveReferences.call(this);
+        this.memberItems.forEach(function (apiItem) {
+            apiItem.resolveReferences();
+        });
+    };
     return ApiItemContainer;
@@ -34,0 +43,0 @@ }(ApiItem_1.default));

lib/definitions/ApiMember.d.ts

@@ -33,2 +33,6 @@ import ApiItem, { IApiItemOptions } from './ApiItem';
     /**
+     * {@inheritdoc ApiItem.onResolveReferences }
+     */
+    protected onResolveReferences(): void;
+    /**
      * Returns a text string such as "someName?: SomeTypeName;", or in the case of a type
@@ -35,0 +39,0 @@ * literal expression, returns a text string such as "someName?:".

lib/definitions/ApiMember.js

@@ -68,2 +68,14 @@ "use strict";
     /**
+     * {@inheritdoc ApiItem.onResolveReferences }
+     */
+    ApiMember.prototype.onResolveReferences = function () {
+        _super.prototype.onResolveReferences.call(this);
+        if (this.typeLiteral) {
+            this.typeLiteral.resolveReferences();
+            this.typeLiteral.memberItems.forEach(function (apiItem) {
+                apiItem.resolveReferences();
+            });
+        }
+    };
+    /**
      * Returns a text string such as "someName?: SomeTypeName;", or in the case of a type
@@ -70,0 +82,0 @@ * literal expression, returns a text string such as "someName?:".

lib/definitions/ApiMethod.js

@@ -30,4 +30,2 @@ "use strict";
                 var declarationSymbol = TypeScriptHelpers_1.default.tryGetSymbolForDeclaration(param);
-                var docComment = declarationSymbol && _this.documentation && _this.documentation.paramDocs ?
-                    _this.documentation.paramDocs.get(declarationSymbol.name) : '';
                 _this.params.push(new ApiParameter_1.default({
@@ -38,3 +36,3 @@ extractor: _this.extractor,
                     jsdocNode: param
-                }, docComment));
+                }));
             }
@@ -41,0 +39,0 @@ }

lib/definitions/ApiParameter.js

@@ -16,3 +16,2 @@ "use strict";
         _this.kind = ApiItem_1.ApiItemKind.Parameter;
-        _this.documentation.docComment = docComment;
         var parameterDeclaration = options.declaration;
@@ -19,0 +18,0 @@ _this.isOptional = !!parameterDeclaration.questionToken || !!parameterDeclaration.initializer;

lib/definitions/ApiProperty.js

@@ -18,3 +18,2 @@ "use strict";
         _this.kind = ApiItem_1.ApiItemKind.Property;
-        _this.isReadOnly = _this.documentation.readonly ? _this.documentation.readonly : false;
         var declaration = options.declaration; /* tslint:disable-line:no-any */
@@ -21,0 +20,0 @@ if (declaration && declaration.type) {

lib/definitions/test/ApiDocumentation.test.js

@@ -23,3 +23,4 @@ /// <reference types="mocha" />
     moduleResolution: ts.ModuleResolutionKind.NodeJs,
-    rootDir: inputFolder
+    rootDir: inputFolder,
+    typeRoots: ['./'] // We need to ignore @types in these tests
 };
@@ -37,3 +38,3 @@ var extractor = new Extractor_1.default({
     function TestApiDocumentation() {
-        return _super.call(this, myDocumentedClass, extractor.docItemLoader, function (msg) { return; }) || this;
+        return _super.call(this, myDocumentedClass, extractor.docItemLoader, extractor, console.log) || this;
     }
@@ -40,0 +41,0 @@ return TestApiDocumentation;

lib/Extractor.js

@@ -42,3 +42,4 @@ "use strict";
         }
-        this.package = new ApiPackage_1.default(this, rootFile);
+        this.package = new ApiPackage_1.default(this, rootFile); // construct members
+        this.package.resolveReferences(); // creates ApiDocumentation
     };
@@ -45,0 +46,0 @@ /**

lib/generators/test/ApiFileGenerator.test.js

@@ -32,3 +32,4 @@ /// <reference types="mocha" />
                 moduleResolution: ts.ModuleResolutionKind.NodeJs,
-                rootDir: inputFolder
+                rootDir: inputFolder,
+                typeRoots: ['./'] // We need to ignore @types in these tests
             };
@@ -35,0 +36,0 @@ var extractor = new Extractor_1.default({

lib/generators/test/ApiJsonGenerator.test.js

@@ -24,3 +24,4 @@ /// <reference types="mocha" />
                 moduleResolution: ts.ModuleResolutionKind.NodeJs,
-                rootDir: inputFolder
+                rootDir: inputFolder,
+                typeRoots: ['./'] // We need to ignore @types in these tests
             };
@@ -27,0 +28,0 @@ var extractor = new Extractor_1.default({

lib/test/DocElementParser.test.js

@@ -39,3 +39,3 @@ /// <reference types="mocha" />
     function TestApiDocumentation() {
-        return _super.call(this, myDocumentedClass, extractor.docItemLoader, function (msg) { return; }) || this;
+        return _super.call(this, myDocumentedClass, extractor.docItemLoader, extractor, console.log) || this;
     }
@@ -42,0 +42,0 @@ TestApiDocumentation.prototype.parseParam = function (tokenizer) {

package.json

 {
   "name": "@microsoft/api-extractor",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "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

528651

increased by1.62%

Lines of code

6278

increased by1.9%

No dependency changes