@microsoft/api-extractor
Advanced tools
Comparing version 1.1.13 to 1.1.14
@@ -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", |
# 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 |
/// <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(); | ||
} |
/* 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; |
@@ -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,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'); |
@@ -12,8 +12,4 @@ import { IApiItemOptions } from './ApiItem'; | ||
constructor(options: IApiItemOptions); | ||
/** | ||
* {@inheritdoc ApiItem.onResolveReferences } | ||
*/ | ||
protected onResolveReferences(): void; | ||
getDeclarationLine(): string; | ||
} | ||
export default ApiProperty; |
@@ -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, { |
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; | ||
} |
"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 @@ }()); |
@@ -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; |
@@ -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 @@ }; |
@@ -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 | ||
} | ||
} | ||
} |
@@ -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 @@ /** |
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); | ||
} |
@@ -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; |
@@ -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) { |
@@ -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 @@ }); |
{ | ||
"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", |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
620124
7635