@microsoft/api-extractor - npm Package Compare versions

Comparing version 1.1.7 to 1.1.8

CHANGELOG.json

@@ -5,2 +5,14 @@ {
     {
+      "version": "1.1.8",
+      "tag": "@microsoft/api-extractor_v1.1.8",
+      "date": "Sat, 04 Feb 2017 02:32:05 GMT",
+      "comments": {
+        "patch": [
+          {
+            "comment": "Moved ApiItem references within ApiDocumentation, to ApiItem caller."
+          }
+        ]
+      }
+    },
+    {
       "version": "1.1.7",
@@ -7,0 +19,0 @@ "tag": "@microsoft/api-extractor_v1.1.7",

CHANGELOG.md

 # Change Log - @microsoft/api-extractor
 
-This log was last generated on Thu, 02 Feb 2017 14:05:53 GMT and should not be manually modified.
+This log was last generated on Sat, 04 Feb 2017 02:32:05 GMT and should not be manually modified.
 
+## 1.1.8
+Sat, 04 Feb 2017 02:32:05 GMT
+
+### Patches
+
+- Moved ApiItem references within ApiDocumentation, to ApiItem caller.
+
 ## 1.1.7
@@ -6,0 +13,0 @@ Thu, 02 Feb 2017 14:05:53 GMT

lib/definitions/ApiDocumentation.d.ts

 /// <reference types="es6-collections" />
-import ApiItem from './ApiItem';
 import { IDocElement, IParam } from '../IDocElement';
@@ -56,4 +55,2 @@ import DocItemLoader from '../DocItemLoader';
 export default class ApiDocumentation {
-    private static _allowedRegularJsdocTags;
-    private static _allowedInlineJsdocTags;
     /**
@@ -63,3 +60,5 @@ * Match JsDoc block tags and inline tags
      */
-    private static _jsdocTagsRegex;
+    static readonly _jsdocTagsRegex: RegExp;
+    private static _allowedRegularJsdocTags;
+    private static _allowedInlineJsdocTags;
     /**
@@ -79,12 +78,7 @@ * Splits an API reference expression into two parts, first part is the scopename/packageName and
     /**
-     * Corresponding ApiItem for this documentation object
-     */
-    apiItem: ApiItem;
-    /**
-     * This returns the JSDoc comment block for the given item (without "/**" characters),
-     * or an empty string if there is no comment.  This propery will never be undefined.
+     * The original JsDoc comment.
      *
-     * Example: "Example Function\n@returns the number of items\n@internal"
+     * Example: "This is a summary. \{\@link a\} \@remarks These are remarks."
      */
-    docComment: string;
+    originalJsDoc: string;
     /**
@@ -113,9 +107,2 @@ * The docComment text string split into an array of ITokenItems.  The tokens are essentially either
     /**
-     * Indicates that this definition does not have adequate JSDoc comments.  If isMissing=true,
-     * then this will be noted in the API file produced by ApiFileGenerator.  (The JSDoc
-     * text itself is not included in that report, because documentation changes do not
-     * require an API review, and thus should not cause a diff for that report.)
-     */
-    isMissing: boolean;
-    /**
      * An "API Tag" is a custom JSDoc tag which indicates whether this definition
@@ -140,3 +127,3 @@ * is considered Public API for third party developers, as well as its release
     isOverride?: boolean;
-    readonly?: boolean;
+    hasReadOnlyTag?: boolean;
     docItemLoader: DocItemLoader;
@@ -160,4 +147,3 @@ /**
     private static parseScopedPackageName(scopedName);
-    constructor(apiItem: ApiItem, docItemLoader: DocItemLoader, extractor: Extractor, errorLogger: (message: string) => void);
-    protected _getJsDocs(apiItem: ApiItem): string;
+    constructor(docComment: string, docItemLoader: DocItemLoader, extractor: Extractor, errorLogger: (message: string) => void);
     protected _parseDocs(): void;
@@ -164,0 +150,0 @@ /**

lib/definitions/ApiDocumentation.js

 /* tslint:disable:no-bitwise */
 "use strict";
-var ts = require("typescript");
-var TypeScriptHelpers_1 = require("../TypeScriptHelpers");
 var DocElementParser_1 = require("../DocElementParser");
 var Token_1 = require("../Token");
 var Tokenizer_1 = require("../Tokenizer");
-var ApiPackage_1 = require("./ApiPackage");
 /**
@@ -44,8 +41,7 @@ * An "API Tag" is a custom JSDoc tag which indicates whether an ApiItem definition
 var ApiDocumentation = (function () {
-    function ApiDocumentation(apiItem, docItemLoader, extractor, errorLogger) {
-        this.apiItem = apiItem;
+    function ApiDocumentation(docComment, docItemLoader, extractor, errorLogger) {
+        this.originalJsDoc = docComment;
         this.docItemLoader = docItemLoader;
         this.extractor = extractor;
         this.reportError = errorLogger;
-        this.docComment = this._getJsDocs(apiItem);
         this.parameters = new Map();
@@ -108,17 +104,4 @@ this._parseDocs();
     };
-    ApiDocumentation.prototype._getJsDocs = function (apiItem) {
-        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?
-        // If not, we consider the definition to be "missingDocumentation".
-        var condensedDocs = jsDoc
-            .replace(ApiDocumentation._jsdocTagsRegex, '')
-            .replace(/[^a-z]/gi, '');
-        this.isMissing = apiItem.shouldHaveDocumentation() && condensedDocs.length <= 10;
-        return jsDoc;
-    };
     ApiDocumentation.prototype._parseDocs = function () {
-        var tokenizer = new Tokenizer_1.default(this.docComment, this.reportError);
+        var tokenizer = new Tokenizer_1.default(this.originalJsDoc, this.reportError);
         this.summary = DocElementParser_1.default.parse(tokenizer, this.reportError);
@@ -202,3 +185,3 @@ this.returnsMessage = [];
                         tokenizer.getToken();
-                        this.readonly = true;
+                        this.hasReadOnlyTag = true;
                         break;
@@ -255,19 +238,6 @@ case '@betadocumentation':
         }
-        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 && this.apiTag !== ApiTag.Internal) {
+            this.reportError('The @preapproved tag may only be applied to @internal defintions');
+            this.preapproved = false;
         }
-        if (this.preapproved) {
-            if (this.apiTag !== ApiTag.Internal) {
-                this.reportError('The @preapproved tag may only be applied to @internal defintions');
-                this.preapproved = false;
-            }
-            else if (!(this.apiItem.getDeclarationSymbol().flags & (ts.SymbolFlags.Interface | ts.SymbolFlags.Class))) {
-                this.reportError('The @preapproved tag may only be applied to classes and interfaces');
-                this.preapproved = false;
-            }
-        }
     };
@@ -380,2 +350,7 @@ /**
 }());
+/**
+ * Match JsDoc block tags and inline tags
+ * Example "@a @b@c d@e @f {whatever} {@link a} { @something } \@g" => ["@a", "@f", "{@link a}", "{ @something }"]
+ */
+ApiDocumentation._jsdocTagsRegex = /{\s*@(\\{|\\}|[^{}])*}|(?:^|\s)(\@[a-z_]+)(?=\s|$)/gi;
 // For guidance about using these tags, please see this document:
@@ -407,7 +382,2 @@ // https://onedrive.visualstudio.com/DefaultCollection/SPPPlat/_git/sp-client
 /**
- * Match JsDoc block tags and inline tags
- * Example "@a @b@c d@e @f {whatever} {@link a} { @something } \@g" => ["@a", "@f", "{@link a}", "{ @something }"]
- */
-ApiDocumentation._jsdocTagsRegex = /{\s*@(\\{|\\}|[^{}])*}|(?:^|\s)(\@[a-z_]+)(?=\s|$)/gi;
-/**
  * Splits an API reference expression into two parts, first part is the scopename/packageName and
@@ -414,0 +384,0 @@ * the second part is the exportName.memberName.

lib/definitions/ApiItem.d.ts

@@ -112,2 +112,10 @@ import * as ts from 'typescript';
     /**
+     * Indicates that this ApiItem does not have adequate JSDoc comments. If shouldHaveDocumentation()=true,
+     * and there is less than 10 characters of summary text in the JSDoc, then this will be set to true and
+     * noted in the API file produced by ApiFileGenerator.
+     * (The JSDoc text itself is not included in that report, because documentation
+     * changes do not require an API review, and thus should not cause a diff for that report.)
+     */
+    needsDocumentation: boolean;
+    /**
      * The Extractor object that acts as the root of the abstract syntax tree that this item belongs to.
@@ -114,0 +122,0 @@ */

lib/definitions/ApiItem.js

@@ -6,2 +6,4 @@ /* tslint:disable:no-bitwise */
 var ApiDocumentation_1 = require("./ApiDocumentation");
+var TypeScriptHelpers_1 = require("../TypeScriptHelpers");
+var DocElementParser_1 = require("../DocElementParser");
 /**
@@ -83,4 +85,4 @@ * Indicates the type of definition represented by a ApiItem object.
         this.reportError = this.reportError.bind(this);
+        this.jsdocNode = options.jsdocNode;
         this.declaration = options.declaration;
-        this.jsdocNode = options.jsdocNode;
         this._errorNode = options.declaration;
@@ -162,4 +164,23 @@ this._state = ResolveState.Unresolved;
     ApiItem.prototype.onResolveReferences = function () {
-        this.documentation = new ApiDocumentation_1.default(this, this.extractor.docItemLoader, this.extractor, this.reportError);
-        // TODO: this.collectTypeReferences(this); 
+        var originalJsDoc = '';
+        if (this.jsdocNode) {
+            originalJsDoc = TypeScriptHelpers_1.default.getJsDocComments(this.jsdocNode, this.reportError);
+        }
+        this.documentation = new ApiDocumentation_1.default(originalJsDoc, this.extractor.docItemLoader, this.extractor, this.reportError);
+        // TODO: this.collectTypeReferences(this);
+        var summaryTextCondensed = DocElementParser_1.default.getAsText(this.documentation.summary, this.reportError).replace(/\s\s/g, ' ');
+        this.needsDocumentation = this.shouldHaveDocumentation() && summaryTextCondensed.length <= 10;
+        if (this.kind === ApiItemKind.Package) {
+            if (this.documentation.apiTag !== ApiDocumentation_1.ApiTag.None) {
+                var tag = '@' + ApiDocumentation_1.ApiTag[this.documentation.apiTag].toLowerCase();
+                this.reportError("The " + tag + " tag is not allowed on the package, which is always public");
+            }
+            this.documentation.apiTag = ApiDocumentation_1.ApiTag.Public;
+        }
+        if (this.documentation.preapproved) {
+            if (!(this.getDeclaration().kind & (ts.SyntaxKind.InterfaceDeclaration | ts.SyntaxKind.ClassDeclaration))) {
+                this.reportError('The @preapproved tag may only be applied to classes and interfaces');
+                this.documentation.preapproved = false;
+            }
+        }
     };
@@ -166,0 +187,0 @@ /**

lib/definitions/ApiProperty.d.ts

@@ -12,4 +12,8 @@ import { IApiItemOptions } from './ApiItem';
     constructor(options: IApiItemOptions);
+    /**
+     * {@inheritdoc ApiItem.onResolveReferences }
+     */
+    protected onResolveReferences(): void;
     getDeclarationLine(): string;
 }
 export default ApiProperty;

lib/definitions/ApiProperty.js

@@ -24,2 +24,11 @@ "use strict";
     }
+    /**
+     * {@inheritdoc ApiItem.onResolveReferences }
+     */
+    ApiProperty.prototype.onResolveReferences = function () {
+        _super.prototype.onResolveReferences.call(this);
+        if (this.documentation.hasReadOnlyTag) {
+            this.isReadOnly = true;
+        }
+    };
     ApiProperty.prototype.getDeclarationLine = function () {
@@ -26,0 +35,0 @@ return _super.prototype.getDeclarationLine.call(this, {

lib/definitions/test/ApiDocumentation.test.js

 /// <reference types="mocha" />
 "use strict";
-var __extends = (this && this.__extends) || function (d, b) {
-    for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p];
-    function __() { this.constructor = d; }
-    d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
-};
 var chai_1 = require("chai");
@@ -30,13 +25,2 @@ var ts = require("typescript");
 });
-var myDocumentedClass;
-/**
- * Dummy class wrapping ApiDocumentation to test its protected methods
- */
-var TestApiDocumentation = (function (_super) {
-    __extends(TestApiDocumentation, _super);
-    function TestApiDocumentation() {
-        return _super.call(this, myDocumentedClass, extractor.docItemLoader, extractor, console.log) || this;
-    }
-    return TestApiDocumentation;
-}(ApiDocumentation_1.default));
 extractor.loadExternalPackages('./testInputs/external-api-json');
@@ -47,3 +31,3 @@ // Run the analyzer once to be used by unit tests
 });
-myDocumentedClass = extractor.package.getSortedMemberItems()
+var myDocumentedClass = extractor.package.getSortedMemberItems()
     .filter(function (apiItem) { return apiItem.name === 'MyDocumentedClass'; })[0];
@@ -53,3 +37,3 @@ describe('ApiDocumentation tests', function () {
     describe('ApiDocumentation internal methods', function () {
-        var apiDoc = new TestApiDocumentation();
+        var apiDoc = new ApiDocumentation_1.default('Some summary\n@remarks and some remarks\n@public', extractor.docItemLoader, extractor, console.log);
         var apiReferenceExpr;
@@ -56,0 +40,0 @@ var expected;

lib/DocElementParser.d.ts

@@ -25,2 +25,3 @@ import { IDocElement, IHrefLinkElement, ICodeLinkElement } from './IDocElement';
     private static _hrefRegEx;
+    static getAsText(collection: IDocElement[], reportError: (message: string) => void): string;
     static makeTextElement(text: string): IDocElement;
@@ -27,0 +28,0 @@ static parse(tokenizer: Tokenizer, reportError: (message: string) => void): IDocElement[];

lib/DocElementParser.js

@@ -7,2 +7,22 @@ "use strict";
     }
+    DocElementParser.getAsText = function (collection, reportError) {
+        var text = '';
+        collection.forEach(function (docElement) {
+            switch (docElement.kind) {
+                case 'textDocElement':
+                    text += docElement.value + " ";
+                    break;
+                case 'linkDocElement':
+                    // links don't count towards the summary
+                    break;
+                case 'seeDocElement':
+                    // see doesn't count towards the summary
+                    break;
+                default:
+                    reportError('Unexpected item in IDocElement collection');
+                    break;
+            }
+        });
+        return text.trim();
+    };
     DocElementParser.makeTextElement = function (text) {
@@ -9,0 +29,0 @@ if (!text) {

lib/example1-output.ts

@@ -17,2 +17,3 @@ // @public
 
+// (undocumented)
 class MyClass {
@@ -19,0 +20,0 @@ // (undocumented)

lib/generators/ApiFileGenerator.d.ts

@@ -23,2 +23,8 @@ import Extractor from '../Extractor';
     /**
+     * We don't want to require documentation for any properties that occur
+     * anywhere within a TypeLiteral. If this value is above 0, then we are
+     * visiting something within a TypeLiteral.
+     */
+    private _insideTypeLiteral;
+    /**
      * Compares the contents of two API files that were created using ApiFileGenerator,
@@ -25,0 +31,0 @@ * and returns true if they are equivalent.  Note that these files are not normally edited

lib/generators/ApiFileGenerator.js

@@ -49,2 +49,3 @@ "use strict";
     ApiFileGenerator.prototype.writeApiFile = function (reportFilename, extractor) {
+        this._insideTypeLiteral = 0;
         var fileContent = this.generateApiFileContent(extractor);
@@ -111,3 +112,5 @@ fs.writeFileSync(reportFilename, fileContent);
         if (apiMember.typeLiteral) {
+            this._insideTypeLiteral += 1;
             this.visit(apiMember.typeLiteral);
+            this._insideTypeLiteral -= 1;
         }
@@ -156,3 +159,4 @@ };
             }
-            if (apiItem.documentation.isMissing) {
+            // If we are anywhere inside a TypeLiteral, _insideTypeLiteral is greater than 0
+            if (this._insideTypeLiteral === 0 && apiItem.needsDocumentation) {
                 if (footer) {
@@ -159,0 +163,0 @@ footer += ' ';

lib/IDocElement.d.ts

 /**
  * The following interfaces represent Doc Elements of a
  * documentation block.
+ *
+ * @remarks if adding a new 'kind', then it is essential that you update the
+ * methods within DocElementParser (getasText() and parse()).
  */
@@ -5,0 +8,0 @@ export interface IBaseDocElement {

lib/test/DocElementParser.test.js

@@ -39,3 +39,3 @@ /// <reference types="mocha" />
     function TestApiDocumentation() {
-        return _super.call(this, myDocumentedClass, extractor.docItemLoader, extractor, console.log) || this;
+        return _super.call(this, 'Some summary\n@remarks and some remarks\n@public', extractor.docItemLoader, extractor, console.log) || this;
     }
@@ -148,3 +148,3 @@ TestApiDocumentation.prototype.parseParam = function (tokenizer) {
             var apiDoc = new TestApiDocumentation();
-            // Don't include the "@param" in the doc string, parseParam() expects this to be processed in a 
+            // Don't include the "@param" in the doc string, parseParam() expects this to be processed in a
             // previous step.
@@ -151,0 +151,0 @@ var docs = 'x - The height in {@link http://wikipedia.org/pixel_units}';

package.json

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

531848

increased by0.6%

Lines of code

6307

increased by0.46%

No dependency changes