Socket
Socket
Sign inDemoInstall

@microsoft/api-extractor

Package Overview
Dependencies
Maintainers
2
Versions
486
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@microsoft/api-extractor - npm Package Compare versions

Comparing version 1.1.13 to 1.1.14

12

CHANGELOG.json

@@ -5,2 +5,14 @@ {

{
"version": "1.1.14",
"tag": "@microsoft/api-extractor_v1.1.14",
"date": "Sat, 18 Feb 2017 02:32:06 GMT",
"comments": {
"patch": [
{
"comment": "Seperated the ApiItem initialization into 3 stages: create documentation that doesn't require resolution, then complete initialization by resolving links and inheritdocs. This allows us to ignore harmless cycles like type references\""
}
]
}
},
{
"version": "1.1.13",

@@ -7,0 +19,0 @@ "tag": "@microsoft/api-extractor_v1.1.13",

9

CHANGELOG.md
# Change Log - @microsoft/api-extractor
This log was last generated on Thu, 16 Feb 2017 22:10:39 GMT and should not be manually modified.
This log was last generated on Sat, 18 Feb 2017 02:32:06 GMT and should not be manually modified.
## 1.1.14
Sat, 18 Feb 2017 02:32:06 GMT
### Patches
- Seperated the ApiItem initialization into 3 stages: create documentation that doesn't require resolution, then complete initialization by resolving links and inheritdocs. This allows us to ignore harmless cycles like type references"
## 1.1.13

@@ -6,0 +13,0 @@ Thu, 16 Feb 2017 22:10:39 GMT

38

lib/definitions/ApiDocumentation.d.ts
/// <reference types="es6-collections" />
import ApiPackage from './ApiPackage';
import { IDocElement, IParam } from '../IDocElement';
import { IDocElement, IParam, ICodeLinkElement } from '../IDocElement';
import ApiDefinitionReference from '../ApiDefinitionReference';

@@ -95,2 +95,16 @@ import Token from '../Token';

/**
* 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 ApiTag
* 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
* have ApiTag.Internal.
*/
incompleteLinks: ICodeLinkElement[];
/**
* 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 ApiTag information before we can deem an inheritdoc token as valid.
*/
incompleteInheritdocs: Token[];
/**
* An "API Tag" is a custom JSDoc tag which indicates whether this definition

@@ -133,15 +147,21 @@ * is considered Public API for third party developers, as well as its release

constructor(docComment: string, referenceResolver: IReferenceResolver, extractor: Extractor, errorLogger: (message: string) => void);
/**
* Executes the implementation details involved in completing the documentation initialization.
* Currently completes link and inheritdocs.
*/
completeInitialization(): void;
protected _parseDocs(): void;
protected _parseParam(tokenizer: Tokenizer): IParam;
/**
* This method parses the semantic information in an \@inheritdoc JSDoc tag and sets
* all the relevant documenation properties from the inherited doc onto the documenation
* of the current api item.
*
* The format for the \@inheritdoc tag is {\@inheritdoc scopeName/packageName:exportName.memberName}.
* For more information on the format see IInheritdocRef.
* 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();
/**
* A processing of inheritdoc 'Tokens'. This processing occurs after we have created documentation
* for all API items.
*/
protected _parseInheritDoc(token: Token): void;
protected _parseParam(tokenizer: Tokenizer): IParam;
private _completeInheritdocs();
private _reportBadJSDocTag(token);
private _checkInheritDocStatus();
}

130

lib/definitions/ApiDocumentation.js
/* tslint:disable:no-bitwise */
"use strict";
var ApiItem_1 = require("./ApiItem");
var DocElementParser_1 = require("../DocElementParser");

@@ -51,9 +50,22 @@ var ApiDefinitionReference_1 = require("../ApiDefinitionReference");

}
/**
* Executes the implementation details involved in completing the documentation initialization.
* Currently completes link and inheritdocs.
*/
ApiDocumentation.prototype.completeInitialization = function () {
// Ensure links are valid
this._completeLinks();
// Ensure inheritdocs are valid
this._completeInheritdocs();
};
ApiDocumentation.prototype._parseDocs = function () {
var tokenizer = new Tokenizer_1.default(this.originalJsDoc, this.reportError);
this.summary = DocElementParser_1.default.parse(tokenizer, this.reportError);
this.summary = [];
this.returnsMessage = [];
this.deprecatedMessage = [];
this.remarks = [];
this.incompleteLinks = [];
this.incompleteInheritdocs = [];
this.apiTag = ApiTag.None;
var tokenizer = new Tokenizer_1.default(this.originalJsDoc, this.reportError);
this.summary = DocElementParser_1.default.parse(this, tokenizer);
var apiTagCount = 0;

@@ -79,3 +91,3 @@ var parsing = true;

this._checkInheritDocStatus();
this.remarks = DocElementParser_1.default.parse(tokenizer, this.reportError);
this.remarks = DocElementParser_1.default.parse(this, tokenizer);
break;

@@ -85,3 +97,3 @@ case '@returns':

this._checkInheritDocStatus();
this.returnsMessage = DocElementParser_1.default.parse(tokenizer, this.reportError);
this.returnsMessage = DocElementParser_1.default.parse(this, tokenizer);
break;

@@ -98,3 +110,3 @@ case '@param':

tokenizer.getToken();
this.deprecatedMessage = DocElementParser_1.default.parse(tokenizer, this.reportError);
this.deprecatedMessage = DocElementParser_1.default.parse(this, tokenizer);
if (!this.deprecatedMessage || this.deprecatedMessage.length === 0) {

@@ -107,3 +119,3 @@ this.reportError("deprecated description required after @deprecated JSDoc tag.");

tokenizer.getToken();
DocElementParser_1.default.parse(tokenizer, this.reportError);
DocElementParser_1.default.parse(this, tokenizer);
break;

@@ -150,14 +162,6 @@ case '@public':

case '@inheritdoc':
tokenizer.getToken();
if (this.summary.length > 0) {
this.reportError('Cannot provide summary in JsDoc if @inheritdoc tag is given');
}
this._parseInheritDoc(token);
this.isDocInherited = true;
DocElementParser_1.default.parse(this, tokenizer);
break;
case '@link':
var linkDocElement = DocElementParser_1.default.parseLinkTag(tokenizer.getToken(), this.reportError);
if (linkDocElement) {
this.summary.push(linkDocElement);
}
DocElementParser_1.default.parse(this, tokenizer);
break;

@@ -194,60 +198,2 @@ default:

};
/**
* This method parses the semantic information in an \@inheritdoc JSDoc tag and sets
* all the relevant documenation properties from the inherited doc onto the documenation
* of the current api item.
*
* The format for the \@inheritdoc tag is {\@inheritdoc scopeName/packageName:exportName.memberName}.
* For more information on the format see IInheritdocRef.
*/
ApiDocumentation.prototype._parseInheritDoc = function (token) {
// Check to make sure the API definition reference is at most one string
var tokenChunks = token.text.split(' ');
if (tokenChunks.length > 1) {
this.reportError('Too many parameters for @inheritdoc inline tag.' +
'The format should be {@inheritdoc scopeName/packageName:exportName}. Extra parameters are ignored');
return;
}
// Create the IApiDefinitionReference object
// Deconstruct the API reference expression 'scopeName/packageName:exportName.memberName'
var apiDefinitionRef = ApiDefinitionReference_1.default.createFromString(token.text, this.reportError);
// if API reference expression is formatted incorrectly then apiDefinitionRef will be undefined
if (!apiDefinitionRef) {
this.reportError('Incorrecty formatted API definition reference');
return;
}
// Atempt to locate the apiDefinitionRef
var resolvedApiItem = this.referenceResolver.resolve(apiDefinitionRef, this.extractor.package, this.reportError);
// If no IDocItem found then nothing to inherit
// But for the time being set the summary to a text object
if (!resolvedApiItem) {
var textDocItem = {
kind: 'textDocElement',
value: "See documentation for " + tokenChunks[0]
};
this.summary = [textDocItem];
return;
}
// inheritdoc found, copy over IDocBase properties
this.summary = resolvedApiItem.summary;
this.remarks = resolvedApiItem.remarks;
// Copy over detailed properties if neccessary
// Add additional cases if needed
switch (resolvedApiItem.kind) {
case ApiItem_1.ApiItemKind.Function:
this.parameters = resolvedApiItem.params;
this.returnsMessage = resolvedApiItem.returnsMessage;
break;
case ApiItem_1.ApiItemKind.Method:
this.parameters = resolvedApiItem.params;
this.returnsMessage = resolvedApiItem.returnsMessage;
break;
}
// Check if inheritdoc is depreacted
// We need to check if this documentation has a deprecated message
// but it may not appear until after this token.
if (resolvedApiItem.deprecatedMessage) {
this.isDocInheritedDeprecated = true;
}
};
ApiDocumentation.prototype._parseParam = function (tokenizer) {

@@ -274,3 +220,3 @@ var paramDescriptionToken = tokenizer.getToken();

// Full param description may contain additional Tokens (Ex: @link)
var remainingElements = DocElementParser_1.default.parse(tokenizer, this.reportError);
var remainingElements = DocElementParser_1.default.parse(this, tokenizer);
var descriptionElements = [commentTextElement].concat(remainingElements);

@@ -284,2 +230,34 @@ var paramDocElement = {

};
/**
* 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 () {
while (this.incompleteLinks.length) {
var codeLink = this.incompleteLinks.pop();
var parts = {
scopeName: codeLink.scopeName,
packageName: codeLink.packageName,
exportName: codeLink.exportName,
memberName: codeLink.memberName
};
var apiDefinitionRef = ApiDefinitionReference_1.default.createFromParts(parts);
var resolvedApiItem = this.referenceResolver.resolve(apiDefinitionRef, this.extractor.package, this.reportError);
// If the apiDefinitionRef can not be found the resolcedApiItem will be
// undefined and an error will have been reported via this.reportError
if (resolvedApiItem && resolvedApiItem.apiTag === ApiTag.Internal) {
this.reportError('Unable to link to \"Internal\" API item');
}
}
};
/**
* A processing of inheritdoc 'Tokens'. This processing occurs after we have created documentation
* for all API items.
*/
ApiDocumentation.prototype._completeInheritdocs = function () {
while (this.incompleteInheritdocs.length) {
var token = this.incompleteInheritdocs.pop();
DocElementParser_1.default.parseInheritDoc(this, token);
}
};
ApiDocumentation.prototype._reportBadJSDocTag = function (token) {

@@ -286,0 +264,0 @@ var supportsRegular = ApiDocumentation._allowedRegularJsdocTags.indexOf(token.tag) >= 0;

4

lib/definitions/ApiItem.d.ts

@@ -220,3 +220,3 @@ import * as ts from 'typescript';

*/
protected onResolveReferences(): void;
protected onCompleteInitialization(): void;
/**

@@ -231,3 +231,3 @@ * This function is a second stage that happens after Extractor.analyze() calls ApiItem constructor to build up

*/
tryResolveReferences(): boolean;
completeInitialization(): void;
/**

@@ -234,0 +234,0 @@ * A procedure for determining if this ApiItem is missing type

59

lib/definitions/ApiItem.js

@@ -59,22 +59,22 @@ /* tslint:disable:no-bitwise */

/**
* The state of resolving the ApiItem's doc comment references inside a recursive call to ApiItem.resolveReferences().
* The state of completing the ApiItem's doc comment references inside a recursive call to ApiItem.resolveReferences().
*/
var ResolveState;
(function (ResolveState) {
var InitializationState;
(function (InitializationState) {
/**
* The references of this ApiItem have not begun to be resolved.
* The references of this ApiItem have not begun to be completed.
*/
ResolveState[ResolveState["Unresolved"] = 0] = "Unresolved";
InitializationState[InitializationState["Incomplete"] = 0] = "Incomplete";
/**
* The refernces of this ApiItem are in the process of being resolved.
* If we encounter this state again during resolution, a circular dependency is
* The refernces of this ApiItem are in the process of being completed.
* If we encounter this state again during completing, a circular dependency
* has occured.
*/
ResolveState[ResolveState["Resolving"] = 1] = "Resolving";
InitializationState[InitializationState["Completing"] = 1] = "Completing";
/**
* The references of this ApiItem have all been resolved and the documentation can
* The references of this ApiItem have all been completed and the documentation can
* now safely be created.
*/
ResolveState[ResolveState["Resolved"] = 2] = "Resolved";
})(ResolveState || (ResolveState = {}));
InitializationState[InitializationState["Completed"] = 2] = "Completed";
})(InitializationState || (InitializationState = {}));
/**

@@ -114,3 +114,3 @@ * ApiItem is an abstract base that represents TypeScript API definitions such as classes,

this._errorNode = options.declaration;
this._state = ResolveState.Unresolved;
this._state = InitializationState.Incomplete;
this.warnings = [];

@@ -122,2 +122,7 @@ this.extractor = options.extractor;

this.typeChecker = this.extractor.typeChecker;
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);
}

@@ -190,8 +195,4 @@ /**

*/
ApiItem.prototype.onResolveReferences = function () {
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);
ApiItem.prototype.onCompleteInitialization = function () {
this.documentation.completeInitialization();
// TODO: this.collectTypeReferences(this);

@@ -223,18 +224,18 @@ var summaryTextCondensed = DocElementParser_1.default.getAsText(this.documentation.summary, this.reportError).replace(/\s\s/g, ' ');

*/
ApiItem.prototype.tryResolveReferences = function () {
ApiItem.prototype.completeInitialization = function () {
switch (this._state) {
case ResolveState.Resolved:
return true;
case ResolveState.Unresolved:
this._state = ResolveState.Resolving;
this.onResolveReferences();
this._state = ResolveState.Resolved;
case InitializationState.Completed:
return;
case InitializationState.Incomplete:
this._state = InitializationState.Completing;
this.onCompleteInitialization();
this._state = InitializationState.Completed;
for (var _i = 0, _a = this.innerItems; _i < _a.length; _i++) {
var innerItem = _a[_i];
innerItem.tryResolveReferences();
innerItem.completeInitialization();
}
return true;
case ResolveState.Resolving:
return;
case InitializationState.Completing:
this.reportError('circular reference');
return false;
return;
default:

@@ -241,0 +242,0 @@ throw new Error('ApiItem state is invalid');

4

lib/definitions/ApiProperty.d.ts

@@ -12,8 +12,4 @@ import { IApiItemOptions } from './ApiItem';

constructor(options: IApiItemOptions);
/**
* {@inheritdoc ApiItem.onResolveReferences }
*/
protected onResolveReferences(): void;
getDeclarationLine(): string;
}
export default ApiProperty;

12

lib/definitions/ApiProperty.js

@@ -18,2 +18,5 @@ "use strict";

_this.kind = ApiItem_1.ApiItemKind.Property;
if (_this.documentation.hasReadOnlyTag) {
_this.isReadOnly = true;
}
var declaration = options.declaration; /* tslint:disable-line:no-any */

@@ -29,11 +32,2 @@ if (declaration.type) {

}
/**
* {@inheritdoc ApiItem.onResolveReferences }
*/
ApiProperty.prototype.onResolveReferences = function () {
_super.prototype.onResolveReferences.call(this);
if (this.documentation.hasReadOnlyTag) {
this.isReadOnly = true;
}
};
ApiProperty.prototype.getDeclarationLine = function () {

@@ -40,0 +34,0 @@ return _super.prototype.getDeclarationLine.call(this, {

14

lib/DocElementParser.d.ts
import { IDocElement, IHrefLinkElement, ICodeLinkElement } from './IDocElement';
import ApiDocumentation from './definitions/ApiDocumentation';
import Token from './Token';

@@ -27,3 +28,3 @@ import Tokenizer from './Tokenizer';

static makeTextElement(text: string): IDocElement;
static parse(tokenizer: Tokenizer, reportError: (message: string) => void): IDocElement[];
static parse(documentation: ApiDocumentation, tokenizer: Tokenizer): IDocElement[];
/**

@@ -43,3 +44,12 @@ * This method parses the semantic information in an \@link JSDoc tag, creates and returns a

*/
static parseLinkTag(tokenItem: Token, reportError: (message: string) => void): IHrefLinkElement | ICodeLinkElement;
static parseLinkTag(documentation: ApiDocumentation, tokenItem: Token): IHrefLinkElement | ICodeLinkElement;
/**
* This method parses the semantic information in an \@inheritdoc JSDoc tag and sets
* all the relevant documenation properties from the inherited doc onto the documenation
* of the current api item.
*
* The format for the \@inheritdoc tag is {\@inheritdoc scopeName/packageName:exportName.memberName}.
* For more information on the format see IInheritdocRef.
*/
static parseInheritDoc(documentation: ApiDocumentation, token: Token): void;
}

100

lib/DocElementParser.js
"use strict";
var ApiDefinitionReference_1 = require("./ApiDefinitionReference");
var ApiItem_1 = require("./definitions/ApiItem");
var Token_1 = require("./Token");

@@ -33,3 +34,3 @@ var DocElementParser = (function () {

};
DocElementParser.parse = function (tokenizer, reportError) {
DocElementParser.parse = function (documentation, tokenizer) {
var docElements = [];

@@ -50,3 +51,3 @@ var parsing = true;

kind: 'seeDocElement',
seeElements: this.parse(tokenizer, reportError)
seeElements: this.parse(documentation, tokenizer)
});

@@ -61,6 +62,18 @@ break;

switch (token.tag) {
case '@inheritdoc':
tokenizer.getToken();
if (docElements.length > 0 || documentation.summary.length > 0) {
documentation.reportError('Cannot provide summary in JsDoc if @inheritdoc tag is given');
}
documentation.incompleteInheritdocs.push(token);
documentation.isDocInherited = true;
break;
case '@link':
var linkDocElement = this.parseLinkTag(token, reportError);
var linkDocElement = this.parseLinkTag(documentation, token);
if (linkDocElement) {
// Push to docElements to retain position in the documentation
docElements.push(linkDocElement);
if (linkDocElement.referenceType === 'code') {
documentation.incompleteLinks.push(linkDocElement);
}
}

@@ -79,3 +92,3 @@ tokenizer.getToken(); // get the link token

else {
reportError("Unidentifiable Token " + token.type + " " + token.tag + " " + token.text);
documentation.reportError("Unidentifiable Token " + token.type + " " + token.tag + " " + token.text);
}

@@ -99,5 +112,5 @@ }

*/
DocElementParser.parseLinkTag = function (tokenItem, reportError) {
DocElementParser.parseLinkTag = function (documentation, tokenItem) {
if (!tokenItem.text) {
reportError('Invalid @link inline token, a url or API definition reference must be given');
documentation.reportError('Invalid @link inline token, a url or API definition reference must be given');
return;

@@ -113,3 +126,3 @@ }

if (pipeSplitContent.length > 2) {
reportError('Invalid @link parameters, at most one pipe character allowed.');
documentation.reportError('Invalid @link parameters, at most one pipe character allowed.');
return;

@@ -123,3 +136,3 @@ }

if (urlContent.length > 1 && urlContent[1] !== '') {
reportError('Invalid @link parameter, url must be a single string.');
documentation.reportError('Invalid @link parameter, url must be a single string.');
return;

@@ -136,3 +149,3 @@ }

// we are processing an API definition reference
var apiDefitionRef = ApiDefinitionReference_1.default.createFromString(pipeSplitContent[0], reportError);
var apiDefitionRef = ApiDefinitionReference_1.default.createFromString(pipeSplitContent[0], documentation.reportError);
// Once we can locate local API definitions, an error should be reported here if not found.

@@ -154,3 +167,3 @@ if (apiDefitionRef) {

if (displayTextParts && displayTextParts[0].length !== pipeSplitContent[1].length) {
reportError('Display name in @link token may only contain alphabetic characters.');
documentation.reportError('Display name in @link token may only contain alphabetic characters.');
return;

@@ -163,2 +176,69 @@ }

};
/**
* This method parses the semantic information in an \@inheritdoc JSDoc tag and sets
* all the relevant documenation properties from the inherited doc onto the documenation
* of the current api item.
*
* The format for the \@inheritdoc tag is {\@inheritdoc scopeName/packageName:exportName.memberName}.
* For more information on the format see IInheritdocRef.
*/
DocElementParser.parseInheritDoc = function (documentation, token) {
// Check to make sure the API definition reference is at most one string
var tokenChunks = token.text.split(' ');
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');
return;
}
// Create the IApiDefinitionReference object
// Deconstruct the API reference expression 'scopeName/packageName:exportName.memberName'
var apiDefinitionRef = ApiDefinitionReference_1.default.createFromString(token.text, documentation.reportError);
// if API reference expression is formatted incorrectly then apiDefinitionRef will be undefined
if (!apiDefinitionRef) {
documentation.reportError('Incorrecty formatted API definition reference');
return;
}
// Atempt to locate the apiDefinitionRef
var resolvedApiItem = documentation.referenceResolver.resolve(apiDefinitionRef, documentation.extractor.package, documentation.reportError);
// If no resolvedApiItem found then nothing to inherit
// But for the time being set the summary to a text object
if (!resolvedApiItem) {
var textDocItem = {
kind: 'textDocElement',
value: "See documentation for " + tokenChunks[0]
};
documentation.summary = [textDocItem];
return;
}
// We are going to copy the resolvedApiItem's documentation
// We must make sure it's documentation can be completed,
// if we cannot, an error will be reported viathe documentation error handler.
// This will only be the case our resolvedApiItem was created from a local
// ApiItem. Resolutions from JSON will have an undefined 'apiItem' property.
// Example: a circular reference will report an error.
if (resolvedApiItem.apiItem) {
resolvedApiItem.apiItem.completeInitialization();
}
// inheritdoc found, copy over IDocBase properties
documentation.summary = resolvedApiItem.summary;
documentation.remarks = resolvedApiItem.remarks;
// Copy over detailed properties if neccessary
// Add additional cases if needed
switch (resolvedApiItem.kind) {
case ApiItem_1.ApiItemKind.Function:
documentation.parameters = resolvedApiItem.params;
documentation.returnsMessage = resolvedApiItem.returnsMessage;
break;
case ApiItem_1.ApiItemKind.Method:
documentation.parameters = resolvedApiItem.params;
documentation.returnsMessage = resolvedApiItem.returnsMessage;
break;
}
// Check if inheritdoc is depreacted
// We need to check if this documentation has a deprecated message
// but it may not appear until after this token.
if (resolvedApiItem.deprecatedMessage) {
documentation.isDocInheritedDeprecated = true;
}
};
return DocElementParser;

@@ -165,0 +245,0 @@ }());

10

lib/DocItemLoader.d.ts

@@ -20,6 +20,8 @@ import { IDocPackage } from './IDocItem';

/**
* A loader for locating the IDocItem associated with a given project and API item.
* The DocItem loader utilizes the json files generated by the API-Extractor ApiJsonGenerator.
* A loader for locating the IDocItem associated with a given project and API item, or
* for locating an ApiItem locally.
* No processing on the IDocItem orApiItem should be done in this class, this class is only
* concerned with communicating state.
* The IDocItem can then be used to enforce correct API usage, like enforcing internal.
* To use to DocItemLoader: provide a projectFolder to construct a instance of the DocItemLoader,
* To use DocItemLoader: provide a projectFolder to construct a instance of the DocItemLoader,
* then use DocItemLoader.getItem to retrieve the IDocItem of a particular API item.

@@ -42,2 +44,4 @@ */

* that we should search within the current ApiPackage to resolve.
* No processing on the ApiItem should be done here, this class is only concerned
* with communicating state.
*/

@@ -44,0 +48,0 @@ resolveLocalReferences(apiDefinitionRef: ApiDefinitionReference, apiPackage: ApiPackage, reportError: (message: string) => void): ResolvedApiItem;

11

lib/DocItemLoader.js

@@ -9,6 +9,8 @@ "use strict";

/**
* A loader for locating the IDocItem associated with a given project and API item.
* The DocItem loader utilizes the json files generated by the API-Extractor ApiJsonGenerator.
* A loader for locating the IDocItem associated with a given project and API item, or
* for locating an ApiItem locally.
* No processing on the IDocItem orApiItem should be done in this class, this class is only
* concerned with communicating state.
* The IDocItem can then be used to enforce correct API usage, like enforcing internal.
* To use to DocItemLoader: provide a projectFolder to construct a instance of the DocItemLoader,
* To use DocItemLoader: provide a projectFolder to construct a instance of the DocItemLoader,
* then use DocItemLoader.getItem to retrieve the IDocItem of a particular API item.

@@ -47,2 +49,4 @@ */

* that we should search within the current ApiPackage to resolve.
* No processing on the ApiItem should be done here, this class is only concerned
* with communicating state.
*/

@@ -75,3 +79,2 @@ DocItemLoader.prototype.resolveLocalReferences = function (apiDefinitionRef, apiPackage, reportError) {

}
apiItem.tryResolveReferences();
return ResolvedApiItem_1.default.createFromApiItem(apiItem);

@@ -78,0 +81,0 @@ };

56

lib/example3-output.json

@@ -55,8 +55,3 @@ {

"deprecatedMessage": [],
"summary": [
{
"kind": "textDocElement",
"value": "See documentation for inheritLocalCircularDependencyOne"
}
],
"summary": [],
"remarks": [],

@@ -69,8 +64,3 @@ "isBeta": false

"deprecatedMessage": [],
"summary": [
{
"kind": "textDocElement",
"value": "See documentation for inheritLocalCircularDependencyOne"
}
],
"summary": [],
"remarks": [],

@@ -291,2 +281,15 @@ "isBeta": false

},
"publicEnum": {
"kind": "enum",
"values": {},
"deprecatedMessage": [],
"summary": [
{
"kind": "textDocElement",
"value": "This enum is public and any API items can safely inherit documentation or link to this item."
}
],
"remarks": [],
"isBeta": false
},
"sourceEnumValuesDoc": {

@@ -331,4 +334,33 @@ "kind": "enum",

"isBeta": false
},
"testingLinks": {
"kind": "enum",
"values": {},
"deprecatedMessage": [],
"summary": [
{
"kind": "textDocElement",
"value": "Here we test that an error is reported when attempting to link to an internal API item."
},
{
"kind": "linkDocElement",
"referenceType": "code",
"scopeName": "",
"packageName": "",
"exportName": "publicEnum",
"memberName": ""
},
{
"kind": "linkDocElement",
"referenceType": "code",
"scopeName": "",
"packageName": "",
"exportName": "internalEnum",
"memberName": ""
}
],
"remarks": [],
"isBeta": false
}
}
}

2

lib/Extractor.js

@@ -43,3 +43,3 @@ "use strict";

this.package = new ApiPackage_1.default(this, rootFile); // construct members
this.package.tryResolveReferences(); // creates ApiDocumentation
this.package.completeInitialization(); // creates ApiDocumentation
};

@@ -46,0 +46,0 @@ /**

8

lib/ResolvedApiItem.d.ts
import ApiItem, { ApiItemKind } from './definitions/ApiItem';
import { ApiTag } from './definitions/ApiDocumentation';
import { IDocElement, IParam } from './IDocElement';

@@ -13,2 +14,3 @@ import { IDocItem } from './IDocItem';

deprecatedMessage: IDocElement[];
apiTag: ApiTag;
isBeta: boolean;

@@ -20,2 +22,6 @@ params: {

/**
* This property will either be an ApiItem or undefined.
*/
apiItem: ApiItem;
/**
* A function to abstract the construction of a ResolvedApiItem instance

@@ -30,3 +36,3 @@ * from an ApiItem.

static createFromJson(docItem: IDocItem): ResolvedApiItem;
private constructor(kind, summary, remarks, deprecatedMessage, isBeta, params, returnsMessage);
private constructor(kind, summary, remarks, deprecatedMessage, isBeta, params, returnsMessage, apiTag, apiItem);
}

12

lib/ResolvedApiItem.js

@@ -9,3 +9,3 @@ "use strict";

var ResolvedApiItem = (function () {
function ResolvedApiItem(kind, summary, remarks, deprecatedMessage, isBeta, params, returnsMessage) {
function ResolvedApiItem(kind, summary, remarks, deprecatedMessage, isBeta, params, returnsMessage, apiTag, apiItem) {
this.kind = kind;

@@ -17,2 +17,4 @@ this.summary = summary;

this.returnsMessage = returnsMessage;
this.apiTag = apiTag;
this.apiItem = apiItem;
}

@@ -24,7 +26,3 @@ /**

ResolvedApiItem.createFromApiItem = function (apiItem) {
var canResolveRefs = apiItem.tryResolveReferences();
if (!canResolveRefs) {
return undefined;
}
return new ResolvedApiItem(apiItem.kind, apiItem.documentation.summary, apiItem.documentation.remarks, apiItem.documentation.deprecatedMessage, apiItem.documentation.apiTag === ApiDocumentation_1.ApiTag.Beta, apiItem.documentation.parameters, apiItem.documentation.returnsMessage);
return new ResolvedApiItem(apiItem.kind, apiItem.documentation.summary, apiItem.documentation.remarks, apiItem.documentation.deprecatedMessage, apiItem.documentation.apiTag === ApiDocumentation_1.ApiTag.Beta, apiItem.documentation.parameters, apiItem.documentation.returnsMessage, apiItem.documentation.apiTag, apiItem);
};

@@ -50,3 +48,3 @@ /**

}
return new ResolvedApiItem(ApiJsonFile_1.default.convertJsonToKind(docItem.kind), docItem.summary, docItem.remarks, docItem.deprecatedMessage, docItem.isBeta, parameters, returnsMessage);
return new ResolvedApiItem(ApiJsonFile_1.default.convertJsonToKind(docItem.kind), docItem.summary, docItem.remarks, docItem.deprecatedMessage, docItem.isBeta, parameters, returnsMessage, ApiDocumentation_1.ApiTag.Public, undefined);
};

@@ -53,0 +51,0 @@ return ResolvedApiItem;

18

lib/test/DocElementParser.test.js

@@ -75,3 +75,3 @@ /// <reference types="mocha" />

];
var actualSummary = DocElementParser_1.default.parse(tokenizer, console.log);
var actualSummary = DocElementParser_1.default.parse(myDocumentedClass.documentation, tokenizer);
JsonFile_1.default.saveJsonFile('./lib/basicDocExpected.json', JSON.stringify(expectedSummary));

@@ -85,3 +85,3 @@ JsonFile_1.default.saveJsonFile('./lib/basicDocActual.json', JSON.stringify(actualSummary));

tokenizer.getToken();
var actualReturn = DocElementParser_1.default.parse(tokenizer, console.log);
var actualReturn = DocElementParser_1.default.parse(myDocumentedClass.documentation, tokenizer);
JsonFile_1.default.saveJsonFile('./lib/returnDocExpected.json', JSON.stringify(expectedReturn));

@@ -118,3 +118,3 @@ JsonFile_1.default.saveJsonFile('./lib/returnDocActual.json', JSON.stringify(actualReturn));

tokenizer.getToken();
var actualDeprecated = DocElementParser_1.default.parse(tokenizer, console.log);
var actualDeprecated = DocElementParser_1.default.parse(myDocumentedClass.documentation, tokenizer);
JsonFile_1.default.saveJsonFile('./lib/deprecatedDocExpected.json', JSON.stringify(expectedDeprecated));

@@ -143,3 +143,3 @@ JsonFile_1.default.saveJsonFile('./lib/deprecatedDocActual.json', JSON.stringify(actualDeprecated));

];
var actualSummary = DocElementParser_1.default.parse(tokenizer, console.log);
var actualSummary = DocElementParser_1.default.parse(myDocumentedClass.documentation, tokenizer);
JsonFile_1.default.saveJsonFile('./lib/seeDocExpected.json', JSON.stringify(expectedSummary));

@@ -181,3 +181,3 @@ JsonFile_1.default.saveJsonFile('./lib/seeDocActual.json', JSON.stringify(actualSummary));

try {
docElements = DocElementParser_1.default.parse(tokenizer, console.log);
docElements = DocElementParser_1.default.parse(myDocumentedClass.documentation, tokenizer);
}

@@ -200,3 +200,3 @@ catch (error) {

try {
docElements = DocElementParser_1.default.parse(tokenizer, console.log);
docElements = DocElementParser_1.default.parse(myDocumentedClass.documentation, tokenizer);
}

@@ -219,3 +219,3 @@ catch (error) {

try {
docElements = DocElementParser_1.default.parse(tokenizer, console.log);
docElements = DocElementParser_1.default.parse(myDocumentedClass.documentation, tokenizer);
}

@@ -240,3 +240,3 @@ catch (error) {

try {
docElements = DocElementParser_1.default.parse(tokenizer, console.log);
docElements = DocElementParser_1.default.parse(myDocumentedClass.documentation, tokenizer);
}

@@ -262,3 +262,3 @@ catch (error) {

try {
docElements = DocElementParser_1.default.parse(tokenizer, console.log);
docElements = DocElementParser_1.default.parse(myDocumentedClass.documentation, tokenizer);
}

@@ -265,0 +265,0 @@ catch (error) {

2

lib/test/DocItemLoader.test.js

@@ -41,3 +41,3 @@ /// <reference types="mocha" />

chai_1.assert.equal(capturedErrors[1].message, 'circular reference');
chai_1.assert.equal(capturedErrors[2].message, 'circular reference');
chai_1.assert.equal(capturedErrors[2].message, 'Unable to link to "Internal" API item');
TestFileComparer_1.default.assertFileMatchesExpected(outputFile, expectedFile);

@@ -44,0 +44,0 @@ });

2

package.json
{
"name": "@microsoft/api-extractor",
"version": "1.1.13",
"version": "1.1.14",
"description": "Validatation, documentation, and auditing for the exported API of a TypeScript package",

@@ -5,0 +5,0 @@ "main": "lib/index.js",

lib/definitions/ApiDocumentation.js.map

Sorry, the diff of this file is not supported yet

lib/definitions/ApiItem.js.map

Sorry, the diff of this file is not supported yet

lib/definitions/ApiProperty.js.map

Sorry, the diff of this file is not supported yet

lib/DocElementParser.js.map

Sorry, the diff of this file is not supported yet

lib/DocItemLoader.js.map

Sorry, the diff of this file is not supported yet

lib/Extractor.js.map

Sorry, the diff of this file is not supported yet

lib/ResolvedApiItem.js.map

Sorry, the diff of this file is not supported yet

lib/test/DocElementParser.test.js.map

Sorry, the diff of this file is not supported yet

lib/test/DocItemLoader.test.js.map

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc