@microsoft/api-extractor - npm Package Compare versions

Comparing version 2.0.9 to 2.0.10

CHANGELOG.json

@@ -5,2 +5,20 @@ {
     {
+      "version": "2.0.10",
+      "tag": "@microsoft/api-extractor_v2.0.10",
+      "date": "Tue, 20 Jun 2017 01:04:54 GMT",
+      "comments": {
+        "patch": [
+          {
+            "comment": "Improved the wording of many error messages"
+          },
+          {
+            "comment": "Fix a bug with parsing of @link tags"
+          },
+          {
+            "comment": "API Extractor now issues warnings for @internal definitions that are not prefixed with an underscore"
+          }
+        ]
+      }
+    },
+    {
       "version": "2.0.9",
@@ -7,0 +25,0 @@ "tag": "@microsoft/api-extractor_v2.0.9",

CHANGELOG.md

 # Change Log - @microsoft/api-extractor
 
-This log was last generated on Sat, 17 Jun 2017 01:02:59 GMT and should not be manually modified.
+This log was last generated on Tue, 20 Jun 2017 01:04:54 GMT and should not be manually modified.
 
+## 2.0.10
+Tue, 20 Jun 2017 01:04:54 GMT
+
+### Patches
+
+- Improved 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
+
 ## 2.0.9
@@ -6,0 +15,0 @@ Sat, 17 Jun 2017 01:02:59 GMT

lib/ApiDefinitionReference.js

@@ -52,6 +52,7 @@ "use strict";
             // the export name is required
-            throw reportError("Api reference expression contains invalid characters: " + apiReferenceExpr);
+            throw reportError("The API item reference contains an invalid \"exportName.memberName\""
+                + (" expression: \"" + apiReferenceExpr + "\""));
         }
         if (!apiReferenceExpr.match(ApiDefinitionReference._exportRegEx)) {
-            throw reportError("Api reference expression contains invalid characters: " + apiReferenceExpr);
+            throw reportError("The API item reference contains invalid characters: \"" + apiReferenceExpr + "\"");
         }
@@ -58,0 +59,0 @@ return ApiDefinitionReference.createFromParts(apiDefRefParts);

lib/basicDocActual.json

@@ -1,1 +0,1 @@
-"[{\"kind\":\"textDocElement\",\"value\":\"This function parses docTokens for the apiLint website\"},{\"kind\":\"linkDocElement\",\"referenceType\":\"href\",\"targetUrl\":\"https://github.com/OfficeDev/office-ui-fabric-react\",\"value\":\"\"}]"
+"[{\"kind\":\"textDocElement\",\"value\":\"This function parses docTokens for the apiLint website\"},{\"kind\":\"linkDocElement\",\"referenceType\":\"href\",\"targetUrl\":\"https://github.com/OfficeDev/office-ui-fabric-react\",\"value\":\"https://github.com/OfficeDev/office-ui-fabric-react\"}]"

lib/basicDocExpected.json

@@ -1,1 +0,1 @@
-"[{\"kind\":\"textDocElement\",\"value\":\"This function parses docTokens for the apiLint website\"},{\"kind\":\"linkDocElement\",\"referenceType\":\"href\",\"targetUrl\":\"https://github.com/OfficeDev/office-ui-fabric-react\",\"value\":\"\"}]"
+"[{\"kind\":\"textDocElement\",\"value\":\"This function parses docTokens for the apiLint website\"},{\"kind\":\"linkDocElement\",\"referenceType\":\"href\",\"targetUrl\":\"https://github.com/OfficeDev/office-ui-fabric-react\",\"value\":\"https://github.com/OfficeDev/office-ui-fabric-react\"}]"

lib/definitions/ApiDocumentation.d.ts

@@ -97,6 +97,6 @@ /// <reference types="es6-collections" />
     /**
-     * A list of link elements to be processed after all basic documentation has been created
-     * for all items in the project. We save the processing for later because we need ReleaseTag
-     * information before we can deem a link element is valid.
-     * Example: If API item A has a link in it's documentation to API item B, then B must not
+     * A list of \@link elements to be post-processed after all basic documentation has been created
+     * for all items in the project.  We save the processing for later because we need ReleaseTag
+     * information before we can determine whether a link element is valid.
+     * Example: If API item A has a \@link in its documentation to API item B, then B must not
      * have ReleaseTag.Internal.
@@ -106,5 +106,6 @@ */
     /**
-     * A list of 'Tokens' that have been recognized as inheritdoc tokens that will be processed
-     * after the basic documentation for all API items is complete. We save the processing for after
-     * because we need ReleaseTag information before we can deem an inheritdoc token as valid.
+     * A list of 'Token' objects that have been recognized as \@inheritdoc tokens that will be processed
+     * after the basic documentation for all API items is complete. We postpone the processing
+     * because we need ReleaseTag information before we can determine whether an \@inheritdoc token
+     * is valid.
      */
@@ -137,3 +138,3 @@ incompleteInheritdocs: Token[];
      * an API definition reference to an item that has friendly
-     * assessible ApiItem properties.
+     * accessible ApiItem properties.
      *
@@ -170,3 +171,3 @@ * Ex: this is useful in the case of parsing inheritdoc expressions,
     private _reportBadAedocTag(token);
-    private _checkInheritDocStatus();
+    private _checkInheritDocStatus(aedocTag);
 }

lib/definitions/ApiDocumentation.js

@@ -89,7 +89,7 @@ /* tslint:disable:no-bitwise */
             }
-            if (token.type === Token_1.TokenType.Tag) {
+            if (token.type === Token_1.TokenType.BlockTag) {
                 switch (token.tag) {
                     case '@remarks':
                         tokenizer.getToken();
-                        this._checkInheritDocStatus();
+                        this._checkInheritDocStatus(token.tag);
                         this.remarks = DocElementParser_1.default.parse(this, tokenizer);
@@ -99,3 +99,3 @@ break;
                         tokenizer.getToken();
-                        this._checkInheritDocStatus();
+                        this._checkInheritDocStatus(token.tag);
                         this.returnsMessage = DocElementParser_1.default.parse(this, tokenizer);
@@ -105,3 +105,3 @@ break;
                         tokenizer.getToken();
-                        this._checkInheritDocStatus();
+                        this._checkInheritDocStatus(token.tag);
                         var param = this._parseParam(tokenizer);
@@ -161,3 +161,3 @@ if (param) {
             }
-            else if (token.type === Token_1.TokenType.Inline) {
+            else if (token.type === Token_1.TokenType.InlineTag) {
                 switch (token.tag) {
@@ -189,10 +189,10 @@ case '@inheritdoc':
                 // This would be a program bug
-                this.reportError("Unexpected token: " + token.type + " " + token.tag + " " + token.text);
+                this.reportError("Unexpected token: " + token.type + " " + token.tag + " \"" + token.text + "\"");
             }
         }
         if (releaseTagCount > 1) {
-            this.reportError('More than one release tag was specified');
+            this.reportError('More than one release tag (@alpha, @beta, etc) was specified');
         }
         if (this.preapproved && this.releaseTag !== ReleaseTag.Internal) {
-            this.reportError('The @preapproved tag may only be applied to @internal defintions');
+            this.reportError('The @preapproved tag may only be applied to @internal definitions');
             this.preapproved = false;
@@ -204,3 +204,3 @@ }
         if (!paramDescriptionToken) {
-            this.reportError('@param tag missing required description');
+            this.reportError('The @param tag is missing a parameter description');
             return;
@@ -210,4 +210,4 @@ }
         if (hyphenIndex < 0) {
-            this.reportError('No hyphens found in the @param line. ' +
-                'There should be a hyphen between the parameter name and its description.');
+            this.reportError('The @param tag is missing the hyphen that delimits the parameter name '
+                + ' and description');
             return;
@@ -219,3 +219,3 @@ }
             if (!comment) {
-                this.reportError('@param tag requires a description following the hyphen');
+                this.reportError('The @param tag is missing a parameter description');
                 return;
@@ -249,6 +249,10 @@ }
             var resolvedApiItem = this.referenceResolver.resolve(apiDefinitionRef, this.extractor.package, this.warnings);
-            // If the apiDefinitionRef can not be found the resolcedApiItem will be
+            // If the apiDefinitionRef can not be found the resolvedApiItem will be
             // undefined and an error will have been reported via this.reportError
-            if (resolvedApiItem && resolvedApiItem.releaseTag === ReleaseTag.Internal) {
-                this.reportError('Unable to link to \"Internal\" API item');
+            if (resolvedApiItem) {
+                if (resolvedApiItem.releaseTag === ReleaseTag.Internal
+                    || resolvedApiItem.releaseTag === ReleaseTag.Alpha) {
+                    this.reportError('The {@link} tag references an @internal or @alpha API item, '
+                        + 'which will not appear in the generated documentation');
+                }
             }
@@ -271,11 +275,11 @@ }
         if (!supportsRegular && !supportsInline) {
-            this.reportError("Unknown AEDoc tag \"" + token.tag + "\"");
+            this.reportError("The JSDoc tag \"" + token.tag + "\" is not supported by AEDoc");
             return;
         }
-        if (token.type === Token_1.TokenType.Inline && !supportsInline) {
-            this.reportError("The AEDoc tag \"" + token.tag + "\" must not use the non-inline syntax (no curly braces)");
+        if (token.type === Token_1.TokenType.InlineTag && !supportsInline) {
+            this.reportError("The AEDoc tag \"" + token.tag + "\" must use the inline tag notation (i.e. with curly braces)");
             return;
         }
-        if (token.type === Token_1.TokenType.Tag && !supportsRegular) {
-            this.reportError("The AEDoc tag \"" + token.tag + "\" must use the inline syntax (with curly braces)");
+        if (token.type === Token_1.TokenType.BlockTag && !supportsRegular) {
+            this.reportError("The AEDoc tag \"" + token.tag + "\" must use the block tag notation (i.e. no curly braces)");
             return;
@@ -286,5 +290,5 @@ }
     };
-    ApiDocumentation.prototype._checkInheritDocStatus = function () {
+    ApiDocumentation.prototype._checkInheritDocStatus = function (aedocTag) {
         if (this.isDocInherited) {
-            this.reportError('Cannot provide additional AEDoc tags if @inheritdoc tag is present');
+            this.reportError("The " + aedocTag + " tag may not be used because this state is provided by the @inheritdoc target");
         }
@@ -291,0 +295,0 @@ };

lib/definitions/ApiItem.js

@@ -230,3 +230,3 @@ /* tslint:disable:no-bitwise */
                 var tag = '@' + ApiDocumentation_1.ReleaseTag[this.documentation.releaseTag].toLowerCase();
-                this.reportError("The " + tag + " tag is not allowed on the package, which is always public");
+                this.reportError("The " + tag + " tag is not allowed on the package, which is always considered to be @public");
             }
@@ -241,5 +241,18 @@ }
         if (this.documentation.isDocInheritedDeprecated && this.documentation.deprecatedMessage.length === 0) {
-            this.reportError('inheritdoc source item is deprecated. ' +
-                'Must provide @deprecated message or remove @inheritdoc inline tag.');
+            this.reportError('The @inheritdoc target has been marked as @deprecated.  ' +
+                'Add a @deprecated message here, or else remove the @inheritdoc relationship.');
         }
+        if (this.name.substr(0, 1) === '_') {
+            if (this.documentation.releaseTag !== ApiDocumentation_1.ReleaseTag.Internal
+                && this.documentation.releaseTag !== ApiDocumentation_1.ReleaseTag.None) {
+                this.reportWarning('The underscore prefix ("_") should only be used with definitions'
+                    + ' that are explicitly marked as @internal');
+            }
+        }
+        else {
+            if (this.documentation.releaseTag === ApiDocumentation_1.ReleaseTag.Internal) {
+                this.reportWarning('Because this definition is explicitly marked as @internal, an underscore prefix ("_")'
+                    + ' should be added to its name');
+            }
+        }
     };
@@ -246,0 +259,0 @@ /**

lib/definitions/ApiNamespace.js

@@ -45,3 +45,6 @@ /* tslint:disable:no-bitwise */
                 if (!followedSymbol.declarations) {
-                    _this.reportWarning("Definition with no declarations: " + exportSymbol.name);
+                    // This is an API Extractor bug, but it could happen e.g. if we upgrade to a new
+                    // version of the TypeScript compiler that introduces new AST variations that we
+                    // haven't tested before.
+                    _this.reportWarning("The definition \"" + exportSymbol.name + "\" has no declarations");
                     continue;
@@ -74,5 +77,5 @@ }
                 }
-                // Typescript VariableDeclaration exist within a VariableDeclarationList,
-                // the VariableDeclarationList exists within a VariableStatement and
-                // this is where the JSDoc comment Node exists.
+                // Typescript's VariableDeclaration AST nodes have an VariableDeclarationList parent,
+                // and the VariableDeclarationList exists within a VariableStatement, which is where
+                // the JSDoc comment Node can be found.
                 // If there is no parent or grandparent of this VariableDeclartion then
@@ -83,4 +86,4 @@ // we do not know how to obtain the JSDoc comment.
                     declaration.parent.parent.kind !== ts.SyntaxKind.VariableStatement) {
-                    _this.reportWarning("Export \"" + exportSymbol.name + "\" expected to have a 'grand' parent " +
-                        '"VariableStatement" in order to obtain JSDoc comment');
+                    _this.reportWarning("Unable to locate the documentation node for \"" + exportSymbol.name + "\"; "
+                        + "this may be an API Extractor bug");
                 }
@@ -87,0 +90,0 @@ else {

lib/definitions/ApiPackage.js

@@ -40,2 +40,5 @@ /* tslint:disable:no-bitwise */
                 if (!followedSymbol.declarations) {
+                    // This is an API Extractor bug, but it could happen e.g. if we upgrade to a new
+                    // version of the TypeScript compiler that introduces new AST variations that we
+                    // haven't tested before.
                     _this.reportWarning("Definition with no declarations: " + exportSymbol.name);
@@ -42,0 +45,0 @@ continue;

lib/definitions/ApiStructuredType.js

@@ -94,3 +94,6 @@ /* tslint:disable:no-bitwise */
             if (!_this.getMemberItem(setterName)) {
-                _this.reportError("Found setter named " + setterName + " with no corresponding getter.           WriteOnly properties are prohibited.");
+                // Normally we treat API design changes as warnings rather than errors.  However,
+                // a missing getter is bizarre enough that it's reasonable to assume it's a mistake,
+                // not a conscious design choice.
+                _this.reportError("The \"" + setterName + "\" property has a setter, but no a getter");
             }
@@ -97,0 +100,0 @@ });

lib/definitions/test/ApiDocumentation.test.js

@@ -48,10 +48,13 @@ /// <reference types="mocha" />
             chai_1.assert.equal(capturedErrors.length, 8);
-            chai_1.assert.equal(capturedErrors[0].message, 'Cannot provide summary in AEDoc if @inheritdoc tag is given');
-            chai_1.assert.equal(capturedErrors[1].message, 'Unknown AEDoc tag "@badAedocTag"');
-            chai_1.assert.equal(capturedErrors[2].message, 'Unknown tag name for inline tag.');
-            chai_1.assert.equal(capturedErrors[3].message, 'Too few parameters for @link inline tag.');
+            chai_1.assert.equal(capturedErrors[0].message, 'A summary block is not allowed here, because the @inheritdoc'
+                + ' target provides the summary');
+            chai_1.assert.equal(capturedErrors[1].message, 'The JSDoc tag "@badAedocTag" is not supported by AEDoc');
+            chai_1.assert.equal(capturedErrors[2].message, 'Invalid call to _tokenizeInline()');
+            chai_1.assert.equal(capturedErrors[3].message, 'The {@link} tag must include a URL or API item reference');
             chai_1.assert.equal(capturedErrors[4].message, 'Unexpected text in AEDoc comment: "can not contain a tag"');
-            chai_1.assert.equal(capturedErrors[5].message, 'More than one release tag was specified');
-            chai_1.assert.equal(capturedErrors[6].message, 'An API item reference must use the notation: "@scopeName/packageName:exportName.memberName"');
-            chai_1.assert.equal(capturedErrors[7].message, 'inheritdoc source item is deprecated. Must provide @deprecated message or remove @inheritdoc inline tag.');
+            chai_1.assert.equal(capturedErrors[5].message, 'More than one release tag (@alpha, @beta, etc) was specified');
+            chai_1.assert.equal(capturedErrors[6].message, 'An API item reference must use the notation:'
+                + ' "@scopeName/packageName:exportName.memberName"');
+            chai_1.assert.equal(capturedErrors[7].message, 'The @inheritdoc target has been marked as @deprecated.  '
+                + 'Add a @deprecated message here, or else remove the @inheritdoc relationship.');
         });
@@ -58,0 +61,0 @@ it('Should parse release tag', function () {

lib/DocElementParser.d.ts

@@ -7,7 +7,8 @@ import { IDocElement, IHrefLinkElement, ICodeLinkElement } from './IDocElement';
     /**
-     * Matches only strings that contain characters for words.
-     * Any non word characters or spaces, will be present in the third entry in the match results
-     * if they exist.
+     * Used to validate the display text for an \@link tag.  The display text can contain any
+     * characters except for certain AEDoc delimiters: "@", "|", "{", "}".
+     * This RegExp matches the first bad character.
+     * Example: "Microsoft's {spec}" --> "{"
      */
-    private static _wordRegEx;
+    private static _displayTextBadCharacterRegEx;
     /**
@@ -35,3 +36,3 @@ * Matches a href reference. This is used to get an idea whether a given reference is for an href
      *
-     * The format for the \@link tag is {\@link url or API defintion reference | display text}, where
+     * The format for the \@link tag is {\@link URL or API defintion reference | display text}, where
      * the '|' is only needed if the optional display text is given.
@@ -38,0 +39,0 @@ *

lib/DocElementParser.js

@@ -45,3 +45,3 @@ "use strict";
             }
-            if (token.type === Token_1.TokenType.Tag) {
+            if (token.type === Token_1.TokenType.BlockTag) {
                 switch (token.tag) {
@@ -60,3 +60,3 @@ case '@see':
             }
-            else if (token.type === Token_1.TokenType.Inline) {
+            else if (token.type === Token_1.TokenType.InlineTag) {
                 switch (token.tag) {
@@ -66,3 +66,4 @@ case '@inheritdoc':
                         if (docElements.length > 0 || documentation.summary.length > 0) {
-                            documentation.reportError('Cannot provide summary in AEDoc if @inheritdoc tag is given');
+                            documentation.reportError('A summary block is not allowed here,'
+                                + ' because the @inheritdoc target provides the summary');
                         }
@@ -93,3 +94,3 @@ documentation.incompleteInheritdocs.push(token);
             else {
-                documentation.reportError("Unidentifiable Token " + token.type + " " + token.tag + " " + token.text);
+                documentation.reportError("Unidentifiable Token " + token.type + " " + token.tag + " \"" + token.text + "\"");
             }
@@ -104,3 +105,3 @@ }
      *
-     * The format for the \@link tag is {\@link url or API defintion reference | display text}, where
+     * The format for the \@link tag is {\@link URL or API defintion reference | display text}, where
      * the '|' is only needed if the optional display text is given.
@@ -116,8 +117,7 @@ *
         if (!tokenItem.text) {
-            documentation.reportError('Invalid @link inline token, a url or API definition reference must be given');
+            documentation.reportError('The {@link} tag must include a URL or API item reference');
             return;
         }
         // Make sure there are no extra pipes
-        var pipeSplitContent = tokenItem.text.split('|');
-        pipeSplitContent = pipeSplitContent.map(function (value) {
+        var pipeSplitContent = tokenItem.text.split('|').map(function (value) {
             if (value) {
@@ -128,13 +128,15 @@ return value.trim();
         if (pipeSplitContent.length > 2) {
-            documentation.reportError('Invalid @link parameters, at most one pipe character allowed.');
-            return;
+            documentation.reportError('The {@link} tag contains more than one pipe character ("|")');
+            return undefined;
         }
+        var addressPart = pipeSplitContent[0];
+        var displayTextPart = pipeSplitContent.length > 1 ? pipeSplitContent[1] : '';
         // Try to guess if the tokenContent is a link or API definition reference
         var linkDocElement;
-        if (tokenItem.text.match(this._hrefRegEx)) {
-            var urlContent = pipeSplitContent[0].split(' ');
-            // Make sure only a single url is given
-            if (urlContent.length > 1 && urlContent[1] !== '') {
-                documentation.reportError('Invalid @link parameter, url must be a single string.');
-                return;
+        if (this._hrefRegEx.test(addressPart)) {
+            // Make sure only a single URL is given
+            if (addressPart.indexOf(' ') >= 0) {
+                documentation.reportError('The {@link} tag contains additional spaces after the URL;'
+                    + ' if the URL contains spaces, encode them using %20; for display text, use a pipe delimiter ("|")');
+                return undefined;
             }
@@ -144,4 +146,4 @@ linkDocElement = {
                 referenceType: 'href',
-                targetUrl: urlContent[0],
-                value: ''
+                targetUrl: addressPart
+                // ("value" will be assigned below)
             };
@@ -151,25 +153,32 @@ }
             // we are processing an API definition reference
-            var apiDefitionRef = ApiDefinitionReference_1.default.createFromString(pipeSplitContent[0], documentation.reportError);
+            var apiDefitionRef = ApiDefinitionReference_1.default.createFromString(addressPart, documentation.reportError);
             // Once we can locate local API definitions, an error should be reported here if not found.
-            if (apiDefitionRef) {
-                linkDocElement = {
-                    kind: 'linkDocElement',
-                    referenceType: 'code',
-                    scopeName: apiDefitionRef.scopeName,
-                    packageName: apiDefitionRef.packageName,
-                    exportName: apiDefitionRef.exportName,
-                    memberName: apiDefitionRef.memberName
-                };
+            if (!apiDefitionRef) {
+                return undefined;
             }
+            linkDocElement = {
+                kind: 'linkDocElement',
+                referenceType: 'code',
+                scopeName: apiDefitionRef.scopeName,
+                packageName: apiDefitionRef.packageName,
+                exportName: apiDefitionRef.exportName,
+                memberName: apiDefitionRef.memberName
+                // ("value" will be assigned below)
+            };
         }
         // If a display name is given, ensure it only contains characters for words.
-        if (linkDocElement && pipeSplitContent.length > 1) {
-            var displayTextParts = pipeSplitContent[1].match(this._wordRegEx);
-            if (displayTextParts && displayTextParts[0].length !== pipeSplitContent[1].length) {
-                documentation.reportError('Display name in @link token may only contain alphabetic characters.');
-                return;
+        if (displayTextPart) {
+            var match = this._displayTextBadCharacterRegEx.exec(displayTextPart);
+            if (match) {
+                documentation.reportError("The {@link} tag's display text contains an unsupported"
+                    + (" character: \"" + match[0] + "\""));
+                return undefined;
             }
             // Full match is valid text
-            linkDocElement.value = displayTextParts[0].trim();
+            linkDocElement.value = displayTextPart;
         }
+        else {
+            // If the display text is not explicitly provided, then use the address as the display text
+            linkDocElement.value = addressPart;
+        }
         return linkDocElement;
@@ -189,4 +198,4 @@ };
         if (tokenChunks.length > 1) {
-            documentation.reportError('Too many parameters for @inheritdoc inline tag.' +
-                'The format should be {@inheritdoc scopeName/packageName:exportName}. Extra parameters are ignored');
+            documentation.reportError('The {@inheritdoc} tag does not match the expected pattern' +
+                ' "{@inheritdoc @scopeName/packageName:exportName}"');
             return;
@@ -199,3 +208,3 @@ }
         if (!apiDefinitionRef) {
-            documentation.reportError('Incorrecty formatted API definition reference');
+            documentation.reportError("Incorrectly formatted API item reference: \"" + token.text + "\"");
             return;
@@ -249,7 +258,8 @@ }
 /**
- * Matches only strings that contain characters for words.
- * Any non word characters or spaces, will be present in the third entry in the match results
- * if they exist.
+ * Used to validate the display text for an \@link tag.  The display text can contain any
+ * characters except for certain AEDoc delimiters: "@", "|", "{", "}".
+ * This RegExp matches the first bad character.
+ * Example: "Microsoft's {spec}" --> "{"
  */
-DocElementParser._wordRegEx = /^([\w\s]*)/;
+DocElementParser._displayTextBadCharacterRegEx = /[@|{}]/;
 /**
@@ -256,0 +266,0 @@ * Matches a href reference. This is used to get an idea whether a given reference is for an href

lib/example1-output.api.ts

@@ -6,2 +6,15 @@ class ___proto__ {
 
+// WARNING: propertyWithNoType has incomplete type information
+// @internal
+class _InternalClass {
+  public _internalMethodWithRedundantUnderscore(): void;
+  // (undocumented)
+  public test(): void;
+}
+
+// @internal (preapproved)
+class _PreapprovedInternalClass {
+}
+
+
 // (undocumented)
@@ -17,6 +30,6 @@ class A extends __proto__, implements hasOwnProperty {
 class AliasClass4 {
+  // @internal
+  public _aliasFunc(): void;
   // (undocumented)
   public aliasField: number;
-  // @internal
-  public aliasFunc(): void;
   // (undocumented)
@@ -35,2 +48,5 @@ public readonly shouldBeReadOnly: number;
 class BetaTaggedClass {
+  // WARNING: The underscore prefix ("_") should only be used with definitions that are explicitly marked as @internal
+  // @alpha
+  public _alphaMethodWithBadUnderscore(): void;
   // @internal
@@ -40,2 +56,5 @@ public _internalMethod(): void;
   public alphaMethod(): void;
+  // WARNING: Because this definition is explicitly marked as @internal, an underscore prefix ("_") should be added to its name
+  // @internal
+  public internalMethodMissingUnderscore(): void;
   public plainMethod(): void;
@@ -50,9 +69,2 @@ }
 
-// WARNING: propertyWithNoType has incomplete type information
-// @internal
-class InternalClass {
-  // (undocumented)
-  public test(): void;
-}
-
 // (undocumented)
@@ -68,7 +80,2 @@ class MyClass {
 
-// @internal (preapproved)
-class PreapprovedInternalClass {
-}
-
-
 // (undocumented)
@@ -75,0 +82,0 @@ export function publicFunction(param: number): string;

lib/example2-output.json

@@ -219,3 +219,3 @@ {
               "kind": "textDocElement",
-              "value": "This doc has {curly braces} which is valid but the inline @link token is missing a pipe between the url and the display text"
+              "value": "This doc has {curly braces} which is valid but the inline @link token is missing a pipe between the URL and the display text"
             },
@@ -222,0 +222,0 @@ {

lib/example3-output.api.ts

@@ -0,1 +1,5 @@
+// @internal
+enum _internalEnum {
+}
+
 enum inheritEnumValues {
@@ -20,6 +24,2 @@ index_one = 1,
 
-// @internal
-enum internalEnum {
-}
-
 interface IStructuredTypeInherit {
@@ -26,0 +26,0 @@ thisIsTypeLiteral: [{name: string, age: number}];

lib/example3-output.json

@@ -347,3 +347,4 @@ {
           "exportName": "publicEnum",
-          "memberName": ""
+          "memberName": "",
+          "value": "publicEnum"
         },
@@ -355,4 +356,5 @@ {
           "packageName": "",
-          "exportName": "internalEnum",
-          "memberName": ""
+          "exportName": "_internalEnum",
+          "memberName": "",
+          "value": "_internalEnum"
         }
@@ -359,0 +361,0 @@ ],

lib/generators/test/ApiFileGenerator.test.js

@@ -50,3 +50,3 @@ /// <reference types="mocha" />
             chai_1.assert.equal(capturedErrors.length, 2);
-            chai_1.assert.equal(capturedErrors[0].message, 'Unknown AEDoc tag "@badAedocTag"');
+            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: '
@@ -53,0 +53,0 @@ + '"(Error #1 is the bad tag) Text can no..."');

lib/IDocElement.d.ts

@@ -33,3 +33,3 @@ /**
     /**
-     * The url that this link element references.
+     * The URL that this link element references.
      */
@@ -68,3 +68,3 @@ targetUrl: string;
     /**
-     * Optional text to display in place of the API reference string url that is
+     * Optional text to display in place of the API reference string URL that is
      * constructed from the ts-spec tool.
@@ -71,0 +71,0 @@ */

lib/nestedParamDocActual.json

@@ -1,1 +0,1 @@
-"{\"name\":\"x\",\"description\":[{\"kind\":\"textDocElement\",\"value\":\"The height in\"},{\"kind\":\"linkDocElement\",\"referenceType\":\"href\",\"targetUrl\":\"http://wikipedia.org/pixel_units\",\"value\":\"\"}]}"
+"{\"name\":\"x\",\"description\":[{\"kind\":\"textDocElement\",\"value\":\"The height in\"},{\"kind\":\"linkDocElement\",\"referenceType\":\"href\",\"targetUrl\":\"http://wikipedia.org/pixel_units\",\"value\":\"http://wikipedia.org/pixel_units\"}]}"

lib/nestedParamDocExpected.json

@@ -1,1 +0,1 @@
-"{\"name\":\"x\",\"description\":[{\"kind\":\"textDocElement\",\"value\":\"The height in\"},{\"kind\":\"linkDocElement\",\"referenceType\":\"href\",\"targetUrl\":\"http://wikipedia.org/pixel_units\",\"value\":\"\"}]}"
+"{\"name\":\"x\",\"description\":[{\"kind\":\"textDocElement\",\"value\":\"The height in\"},{\"kind\":\"linkDocElement\",\"referenceType\":\"href\",\"targetUrl\":\"http://wikipedia.org/pixel_units\",\"value\":\"http://wikipedia.org/pixel_units\"}]}"

lib/test/DocElementParser.test.js

@@ -88,3 +88,3 @@ /// <reference types="mocha" />
                     targetUrl: 'https://github.com/OfficeDev/office-ui-fabric-react',
-                    value: ''
+                    value: 'https://github.com/OfficeDev/office-ui-fabric-react'
                 }
@@ -181,3 +181,3 @@ ];
                     targetUrl: 'http://wikipedia.org/pixel_units',
-                    value: ''
+                    value: 'http://wikipedia.org/pixel_units'
                 }
@@ -195,3 +195,3 @@ ];
         });
-        it('Should parse @link with url', function () {
+        it('Should parse @link with URL', function () {
             clearCapturedErrors();
@@ -213,6 +213,6 @@ var docs = '{@link https://microsoft.com}';
             chai_1.assert.equal(linkDocElement.targetUrl, 'https://microsoft.com');
-            chai_1.assert.equal(linkDocElement.value, '');
+            chai_1.assert.equal(linkDocElement.value, 'https://microsoft.com');
             assertCapturedErrors([]);
         });
-        it('Should parse @link with url and text', function () {
+        it('Should parse @link with URL and text', function () {
             clearCapturedErrors();
@@ -251,6 +251,23 @@ var docs = '{@link https://microsoft.com | microsoft home}';
             chai_1.assert.isUndefined(errorMessage);
-            assertCapturedErrors(['Invalid @link parameter, url must be a single string.']);
+            assertCapturedErrors(['The {@link} tag contains additional spaces after the URL; if the URL'
+                    + ' contains spaces, encode them using %20; for display text, use a pipe delimiter ("|")']);
         });
-        it('Should parse @link with API defintion reference', function () {
+        it('Should reject @link with bad display text character', function () {
             clearCapturedErrors();
+            var docs = '{@link https://example.com | Ex@ample}';
+            var tokenizer = new Tokenizer_1.default(docs, console.log);
+            var docElements;
+            /* tslint:disable-next-line:no-any */
+            var errorMessage;
+            try {
+                docElements = DocElementParser_1.default.parse(myDocumentedClass.documentation, tokenizer);
+            }
+            catch (error) {
+                errorMessage = error;
+            }
+            chai_1.assert.isUndefined(errorMessage);
+            assertCapturedErrors(['The {@link} tag\'s display text contains an unsupported character: "@"']);
+        });
+        it('Should parse @link with API definition reference', function () {
+            clearCapturedErrors();
             var docs = '{@link @microsoft/sp-core-library:Guid.equals}';
@@ -313,3 +330,3 @@ var tokenizer = new Tokenizer_1.default(docs, console.log);
             chai_1.assert.isNotNull(errorMessage);
-            assertCapturedErrors(['Invalid @link parameters, at most one pipe character allowed.']);
+            assertCapturedErrors(['The {@link} tag contains more than one pipe character ("|")']);
         });
@@ -316,0 +333,0 @@ });

lib/test/DocItemLoader.test.js

@@ -16,2 +16,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.');
+}
 // These warnings would normally be printed at the bottom
@@ -52,5 +55,7 @@ // of the source package's '*.api.ts' file.
             apiFileGenerator.writeApiFile(outputApiFile, extractor);
-            chai_1.assert.equal(capturedErrors.length, 2);
-            chai_1.assert.equal(capturedErrors[0].message, 'circular reference');
-            chai_1.assert.equal(capturedErrors[1].message, 'Unable to link to "Internal" API item');
+            assertCapturedErrors([
+                'circular reference',
+                'The {@link} tag references an @internal or @alpha API item,'
+                    + ' which will not appear in the generated documentation'
+            ]);
             TestFileComparer_1.default.assertFileMatchesExpected(outputJsonFile, expectedJsonFile);
@@ -57,0 +62,0 @@ TestFileComparer_1.default.assertFileMatchesExpected(outputApiFile, expectedApiFile);

lib/test/Token.test.js

@@ -16,8 +16,8 @@ /// <reference types="mocha" />
             chai_1.assert.equal(token.text, 'Some text');
-            token = new Token_1.default(Token_1.TokenType.Tag, '@tagA');
-            chai_1.assert.equal(token.type, Token_1.TokenType.Tag);
+            token = new Token_1.default(Token_1.TokenType.BlockTag, '@tagA');
+            chai_1.assert.equal(token.type, Token_1.TokenType.BlockTag);
             chai_1.assert.equal(token.tag, '@tagA');
             chai_1.assert.equal(token.text, '');
-            token = new Token_1.default(Token_1.TokenType.Inline, '@link', 'http://www.microsoft.com');
-            chai_1.assert.equal(token.type, Token_1.TokenType.Inline);
+            token = new Token_1.default(Token_1.TokenType.InlineTag, '@link', 'http://www.microsoft.com');
+            chai_1.assert.equal(token.type, Token_1.TokenType.InlineTag);
             chai_1.assert.equal(token.tag, '@link');
@@ -38,3 +38,3 @@ chai_1.assert.equal(token.text, 'http://www.microsoft.com');
             try {
-                token.requireType(Token_1.TokenType.Tag);
+                token.requireType(Token_1.TokenType.BlockTag);
             }
@@ -41,0 +41,0 @@ catch (error) {

lib/test/Tokenizer.test.js

@@ -44,7 +44,7 @@ /// <reference types="mocha" />
                 new Token_1.default(Token_1.TokenType.Text, '', 'this is a mock documentation'),
-                new Token_1.default(Token_1.TokenType.Tag, '@taga'),
+                new Token_1.default(Token_1.TokenType.BlockTag, '@taga'),
                 new Token_1.default(Token_1.TokenType.Text, '', 'hi'),
-                new Token_1.default(Token_1.TokenType.Tag, '@tagb'),
+                new Token_1.default(Token_1.TokenType.BlockTag, '@tagb'),
                 new Token_1.default(Token_1.TokenType.Text, '', 'hello @invalid@tag [e-mail]'),
-                new Token_1.default(Token_1.TokenType.Tag, '@tagc'),
+                new Token_1.default(Token_1.TokenType.BlockTag, '@tagc'),
                 new Token_1.default(Token_1.TokenType.Text, '', 'this is'),
@@ -60,3 +60,3 @@ new Token_1.default(Token_1.TokenType.Text, '', 'and this is {just curly braces}')
             var token = '{    @link   https://bing.com  |  Bing  }';
-            var expectedToken = new Token_1.default(Token_1.TokenType.Inline, '@link', 'https://bing.com | Bing');
+            var expectedToken = new Token_1.default(Token_1.TokenType.InlineTag, '@link', 'https://bing.com | Bing');
             var actualToken = testTokenizer.tokenizeInline(token);
@@ -63,0 +63,0 @@ chai_1.assert.equal(expectedToken.type, actualToken.type);

lib/Token.d.ts

@@ -10,9 +10,9 @@ /**
     /**
-     * A Token that specifies a tag.
-     * Example: \@link, \@internal, etc.
+     * A Token representing an AEDoc block tag.
+     * Example: \@public, \@remarks, etc.
      */
-    Tag = 1,
+    BlockTag = 1,
     /**
-     * This is a specific kind of Tag that is important to
-     * distinguish because it contains additional parameters.
+     * A Token representing an AEDoc inline tag.  Inline tags must be enclosed in
+     * curly braces, which may include parameters.
      *
@@ -23,3 +23,3 @@ * Example:
      */
-    Inline = 2,
+    InlineTag = 2,
 }
@@ -26,0 +26,0 @@ /**

lib/Token.js

@@ -13,9 +13,9 @@ "use strict";
     /**
-     * A Token that specifies a tag.
-     * Example: \@link, \@internal, etc.
+     * A Token representing an AEDoc block tag.
+     * Example: \@public, \@remarks, etc.
      */
-    TokenType[TokenType["Tag"] = 1] = "Tag";
+    TokenType[TokenType["BlockTag"] = 1] = "BlockTag";
     /**
-     * This is a specific kind of Tag that is important to
-     * distinguish because it contains additional parameters.
+     * A Token representing an AEDoc inline tag.  Inline tags must be enclosed in
+     * curly braces, which may include parameters.
      *
@@ -26,3 +26,3 @@ * Example:
      */
-    TokenType[TokenType["Inline"] = 2] = "Inline";
+    TokenType[TokenType["InlineTag"] = 2] = "InlineTag";
 })(TokenType = exports.TokenType || (exports.TokenType = {}));
@@ -29,0 +29,0 @@ /**

lib/Tokenizer.js

@@ -38,3 +38,3 @@ "use strict";
             if (value.charAt(0) === '@') {
-                token = new Token_1.default(Token_1.TokenType.Tag, value);
+                token = new Token_1.default(Token_1.TokenType.BlockTag, value);
             }
@@ -59,8 +59,9 @@ else if (value.charAt(0) === '{' && value.charAt(value.length - 1) === '}') {
         if (docEntry.charAt(0) !== '{' || docEntry.charAt(docEntry.length - 1) !== '}') {
-            this._reportError('All inline tags should be wrapped inside curly braces.');
-            return;
+            // This is a program bug, since _tokenizeDocs() checks this condition before calling
+            this._reportError('The AEDoc tag is not enclosed in "{" and "}"');
         }
         var tokenContent = docEntry.slice(1, docEntry.length - 1).trim();
         if (tokenContent.charAt(0) !== '@') {
-            this._reportError('Content of inline tags should start with a leading \'@\'.');
+            // This is a program bug, since it should have already been validated by the Tokenizer
+            this._reportError('The AEDoc tag does not start with "@".');
             return;
@@ -70,4 +71,4 @@ }
         if (unescapedCurlyBraces.test(tokenContent)) {
-            this._reportError("Unescaped '{' or '}' detected inside an inline tag. " +
-                'Use \\ to escape curly braces inside inline tags.');
+            this._reportError("An unescaped \"{\" or \"}\" character was found inside an inline tag. " +
+                'Use a backslash ("\\") to escape curly braces.');
             return;
@@ -80,7 +81,7 @@ }
             if (tokenChunks.length < 2) {
-                this._reportError('Too few parameters for @link inline tag.');
+                this._reportError('The {@link} tag must include a URL or API item reference');
                 return;
             }
             tokenChunks.shift(); // Gets rid of '@link'
-            var token = new Token_1.default(Token_1.TokenType.Inline, '@link', tokenChunks.join(' '));
+            var token = new Token_1.default(Token_1.TokenType.InlineTag, '@link', tokenChunks.join(' '));
             return token;
@@ -90,6 +91,7 @@ }
             tokenChunks.shift(); // Gets rid of '@inheritdoc'
-            var token = new Token_1.default(Token_1.TokenType.Inline, '@inheritdoc', tokenChunks.join(' '));
+            var token = new Token_1.default(Token_1.TokenType.InlineTag, '@inheritdoc', tokenChunks.join(' '));
             return token;
         }
-        this._reportError('Unknown tag name for inline tag.');
+        // This is a program bug
+        this._reportError('Invalid call to _tokenizeInline()');
         return;
@@ -96,0 +98,0 @@ };

package.json

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

761950

increased by1.47%

Lines of code

9550

increased by1%

No dependency changes