@microsoft/api-extractor
Advanced tools
Comparing version 3.0.0 to 3.1.0
@@ -5,2 +5,19 @@ { | ||
{ | ||
"version": "3.1.0", | ||
"tag": "@microsoft/api-extractor_v3.1.0", | ||
"date": "Sat, 02 Sep 2017 01:04:26 GMT", | ||
"comments": { | ||
"minor": [ | ||
{ | ||
"comment": "Expanded the api-extractor API to expose interfaces for the *.api.json file fileformat" | ||
} | ||
], | ||
"dependency": [ | ||
{ | ||
"comment": "Updating dependency \"@microsoft/node-core-library\" from `~0.2.2` to `~0.2.3`" | ||
} | ||
] | ||
} | ||
}, | ||
{ | ||
"version": "3.0.0", | ||
@@ -7,0 +24,0 @@ "tag": "@microsoft/api-extractor_v3.0.0", |
# Change Log - @microsoft/api-extractor | ||
This log was last generated on Thu, 31 Aug 2017 18:41:18 GMT and should not be manually modified. | ||
This log was last generated on Sat, 02 Sep 2017 01:04:26 GMT and should not be manually modified. | ||
## 3.1.0 | ||
Sat, 02 Sep 2017 01:04:26 GMT | ||
### Minor changes | ||
- Expanded the api-extractor API to expose interfaces for the *.api.json file fileformat | ||
## 3.0.0 | ||
@@ -6,0 +13,0 @@ Thu, 31 Aug 2017 18:41:18 GMT |
@@ -1,5 +0,5 @@ | ||
import { IDocElement, IHrefLinkElement, ICodeLinkElement } from './IDocElement'; | ||
import ApiDocumentation from './definitions/ApiDocumentation'; | ||
import Token from './Token'; | ||
import Tokenizer from './Tokenizer'; | ||
import { IDocElement, IHrefLinkElement, ICodeLinkElement } from './markup/OldMarkup'; | ||
import ApiDocumentation from './aedoc/ApiDocumentation'; | ||
import Token from './aedoc/Token'; | ||
import Tokenizer from './aedoc/Tokenizer'; | ||
export default class DocElementParser { | ||
@@ -6,0 +6,0 @@ /** |
@@ -6,4 +6,4 @@ "use strict"; | ||
var ApiDefinitionReference_1 = require("./ApiDefinitionReference"); | ||
var ApiItem_1 = require("./definitions/ApiItem"); | ||
var Token_1 = require("./Token"); | ||
var AstItem_1 = require("./ast/AstItem"); | ||
var Token_1 = require("./aedoc/Token"); | ||
var DocElementParser = (function () { | ||
@@ -205,6 +205,6 @@ function DocElementParser() { | ||
// Atempt to locate the apiDefinitionRef | ||
var resolvedApiItem = documentation.referenceResolver.resolve(apiDefinitionRef, documentation.extractor.package, warnings); | ||
// If no resolvedApiItem found then nothing to inherit | ||
var resolvedAstItem = documentation.referenceResolver.resolve(apiDefinitionRef, documentation.extractor.package, warnings); | ||
// If no resolvedAstItem found then nothing to inherit | ||
// But for the time being set the summary to a text object | ||
if (!resolvedApiItem) { | ||
if (!resolvedAstItem) { | ||
var textDocItem = { | ||
@@ -217,24 +217,24 @@ kind: 'textDocElement', | ||
} | ||
// We are going to copy the resolvedApiItem's documentation | ||
// We are going to copy the resolvedAstItem'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. | ||
// This will only be the case our resolvedAstItem was created from a local | ||
// AstItem. Resolutions from JSON will have an undefined 'astItem' property. | ||
// Example: a circular reference will report an error. | ||
if (resolvedApiItem.apiItem) { | ||
resolvedApiItem.apiItem.completeInitialization(); | ||
if (resolvedAstItem.astItem) { | ||
resolvedAstItem.astItem.completeInitialization(); | ||
} | ||
// inheritdoc found, copy over IDocBase properties | ||
documentation.summary = resolvedApiItem.summary; | ||
documentation.remarks = resolvedApiItem.remarks; | ||
// inheritdoc found, copy over IApiBaseDefinition properties | ||
documentation.summary = resolvedAstItem.summary; | ||
documentation.remarks = resolvedAstItem.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; | ||
switch (resolvedAstItem.kind) { | ||
case AstItem_1.AstItemKind.Function: | ||
documentation.parameters = resolvedAstItem.params; | ||
documentation.returnsMessage = resolvedAstItem.returnsMessage; | ||
break; | ||
case ApiItem_1.ApiItemKind.Method: | ||
documentation.parameters = resolvedApiItem.params; | ||
documentation.returnsMessage = resolvedApiItem.returnsMessage; | ||
case AstItem_1.AstItemKind.Method: | ||
documentation.parameters = resolvedAstItem.params; | ||
documentation.returnsMessage = resolvedAstItem.returnsMessage; | ||
break; | ||
@@ -245,3 +245,3 @@ } | ||
// but it may not appear until after this token. | ||
if (resolvedApiItem.deprecatedMessage.length > 0) { | ||
if (resolvedAstItem.deprecatedMessage.length > 0) { | ||
documentation.isDocInheritedDeprecated = true; | ||
@@ -248,0 +248,0 @@ } |
@@ -1,4 +0,4 @@ | ||
import { IDocPackage } from './IDocItem'; | ||
import { IApiPackage } from './api/ApiItem'; | ||
import ApiDefinitionReference from './ApiDefinitionReference'; | ||
import ApiPackage from './definitions/ApiPackage'; | ||
import AstPackage from './ast/AstPackage'; | ||
import ResolvedApiItem from './ResolvedApiItem'; | ||
@@ -20,9 +20,9 @@ /** | ||
/** | ||
* 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 | ||
* A loader for locating the ApiItem associated with a given project and API item, or | ||
* for locating an AstItem locally. | ||
* No processing on the ApiItem orAstItem 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. | ||
* The ApiItem can then be used to enforce correct API usage, like enforcing internal. | ||
* 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. | ||
* then use DocItemLoader.getItem to retrieve the ApiItem of a particular API item. | ||
*/ | ||
@@ -40,13 +40,13 @@ export default class DocItemLoader { | ||
*/ | ||
resolve(apiDefinitionRef: ApiDefinitionReference, apiPackage: ApiPackage, warnings: string[]): ResolvedApiItem; | ||
resolve(apiDefinitionRef: ApiDefinitionReference, astPackage: AstPackage, warnings: string[]): ResolvedApiItem; | ||
/** | ||
* Resolution of API definition references in the scenario that the reference given indicates | ||
* that we should search within the current ApiPackage to resolve. | ||
* No processing on the ApiItem should be done here, this class is only concerned | ||
* that we should search within the current AstPackage to resolve. | ||
* No processing on the AstItem should be done here, this class is only concerned | ||
* with communicating state. | ||
*/ | ||
resolveLocalReferences(apiDefinitionRef: ApiDefinitionReference, apiPackage: ApiPackage, warnings: string[]): ResolvedApiItem; | ||
resolveLocalReferences(apiDefinitionRef: ApiDefinitionReference, astPackage: AstPackage, warnings: string[]): ResolvedApiItem; | ||
/** | ||
* Resolution of API definition references in the scenario that the reference given indicates | ||
* that we should search outside of this ApiPackage and instead search within the JSON API file | ||
* that we should search outside of this AstPackage and instead search within the JSON API file | ||
* that is associated with the apiDefinitionRef. | ||
@@ -56,3 +56,3 @@ */ | ||
/** | ||
* Attempts to locate and load the IDocPackage object from the project folder's | ||
* Attempts to locate and load the IApiPackage object from the project folder's | ||
* node modules. If the package already exists in the cache, nothing is done. | ||
@@ -62,3 +62,3 @@ * | ||
*/ | ||
getPackage(apiDefinitionRef: ApiDefinitionReference): IDocPackage; | ||
getPackage(apiDefinitionRef: ApiDefinitionReference): IApiPackage; | ||
/** | ||
@@ -68,3 +68,3 @@ * Loads the API documentation json file and validates that it conforms to our schema. If it does, | ||
*/ | ||
loadPackageIntoCache(apiJsonFilePath: string, cachePackageName: string): IDocPackage; | ||
loadPackageIntoCache(apiJsonFilePath: string, cachePackageName: string): IApiPackage; | ||
} |
@@ -9,13 +9,13 @@ "use strict"; | ||
var node_core_library_1 = require("@microsoft/node-core-library"); | ||
var ApiItemContainer_1 = require("./definitions/ApiItemContainer"); | ||
var AstItemContainer_1 = require("./ast/AstItemContainer"); | ||
var ResolvedApiItem_1 = require("./ResolvedApiItem"); | ||
var ApiJsonGenerator_1 = require("./generators/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 | ||
* A loader for locating the ApiItem associated with a given project and API item, or | ||
* for locating an AstItem locally. | ||
* No processing on the ApiItem orAstItem 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. | ||
* The ApiItem can then be used to enforce correct API usage, like enforcing internal. | ||
* 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. | ||
* then use DocItemLoader.getItem to retrieve the ApiItem of a particular API item. | ||
*/ | ||
@@ -37,11 +37,11 @@ var DocItemLoader = (function () { | ||
*/ | ||
DocItemLoader.prototype.resolve = function (apiDefinitionRef, apiPackage, warnings) { | ||
DocItemLoader.prototype.resolve = function (apiDefinitionRef, astPackage, warnings) { | ||
// We determine if an 'apiDefinitionRef' is local if it has no package name or if the scoped | ||
// package name is equal to the current package's scoped package name. | ||
if (!apiDefinitionRef.packageName || apiDefinitionRef.toScopePackageString() === apiPackage.name) { | ||
if (!apiDefinitionRef.packageName || apiDefinitionRef.toScopePackageString() === astPackage.name) { | ||
// Resolution for local references | ||
return this.resolveLocalReferences(apiDefinitionRef, apiPackage, warnings); | ||
return this.resolveLocalReferences(apiDefinitionRef, astPackage, warnings); | ||
} | ||
else { | ||
// If there was no resolved apiItem then try loading from JSON | ||
// If there was no resolved astItem then try loading from JSON | ||
return this.resolveJsonReferences(apiDefinitionRef, warnings); | ||
@@ -52,10 +52,10 @@ } | ||
* Resolution of API definition references in the scenario that the reference given indicates | ||
* that we should search within the current ApiPackage to resolve. | ||
* No processing on the ApiItem should be done here, this class is only concerned | ||
* that we should search within the current AstPackage to resolve. | ||
* No processing on the AstItem should be done here, this class is only concerned | ||
* with communicating state. | ||
*/ | ||
DocItemLoader.prototype.resolveLocalReferences = function (apiDefinitionRef, apiPackage, warnings) { | ||
var apiItem = apiPackage.getMemberItem(apiDefinitionRef.exportName); | ||
DocItemLoader.prototype.resolveLocalReferences = function (apiDefinitionRef, astPackage, warnings) { | ||
var astItem = astPackage.getMemberItem(apiDefinitionRef.exportName); | ||
// Check if export name was not found | ||
if (!apiItem) { | ||
if (!astItem) { | ||
warnings.push("Unable to find referenced export \"" + apiDefinitionRef.toExportString() + "\""); | ||
@@ -66,14 +66,14 @@ return undefined; | ||
if (apiDefinitionRef.memberName) { | ||
if (apiItem instanceof ApiItemContainer_1.default) { | ||
var apiItemContainer = apiItem; | ||
if (astItem instanceof AstItemContainer_1.default) { | ||
var astItemContainer = astItem; | ||
// get() returns undefined if there is no match | ||
apiItem = apiItemContainer.getMemberItem(apiDefinitionRef.memberName); | ||
astItem = astItemContainer.getMemberItem(apiDefinitionRef.memberName); | ||
} | ||
else { | ||
// There are no other instances of apiItem that has members, | ||
// There are no other instances of astItem that has members, | ||
// thus there must be a mistake with the apiDefinitionRef. | ||
apiItem = undefined; | ||
astItem = undefined; | ||
} | ||
} | ||
if (!apiItem) { | ||
if (!astItem) { | ||
// If we are here, we can be sure there was a problem with the memberName. | ||
@@ -84,7 +84,7 @@ // memberName was not found, apiDefinitionRef is invalid | ||
} | ||
return ResolvedApiItem_1.default.createFromApiItem(apiItem); | ||
return ResolvedApiItem_1.default.createFromAstItem(astItem); | ||
}; | ||
/** | ||
* Resolution of API definition references in the scenario that the reference given indicates | ||
* that we should search outside of this ApiPackage and instead search within the JSON API file | ||
* that we should search outside of this AstPackage and instead search within the JSON API file | ||
* that is associated with the apiDefinitionRef. | ||
@@ -143,3 +143,3 @@ */ | ||
/** | ||
* Attempts to locate and load the IDocPackage object from the project folder's | ||
* Attempts to locate and load the IApiPackage object from the project folder's | ||
* node modules. If the package already exists in the cache, nothing is done. | ||
@@ -175,3 +175,3 @@ * | ||
DocItemLoader.prototype.loadPackageIntoCache = function (apiJsonFilePath, cachePackageName) { | ||
var apiPackage = node_core_library_1.JsonFile.loadAndValidateWithCallback(apiJsonFilePath, ApiJsonGenerator_1.default.jsonSchema, function (errorInfo) { | ||
var astPackage = node_core_library_1.JsonFile.loadAndValidateWithCallback(apiJsonFilePath, ApiJsonGenerator_1.default.jsonSchema, function (errorInfo) { | ||
var errorMessage = path.basename(apiJsonFilePath) + ' does not conform to the expected schema.' + os.EOL | ||
@@ -183,4 +183,4 @@ + '(Was it created by an incompatible release of API Extractor?)' + os.EOL | ||
}); | ||
this._cache.set(cachePackageName, apiPackage); | ||
return apiPackage; | ||
this._cache.set(cachePackageName, astPackage); | ||
return astPackage; | ||
}; | ||
@@ -187,0 +187,0 @@ return DocItemLoader; |
import * as ts from 'typescript'; | ||
import { PackageJsonLookup } from '@microsoft/node-core-library'; | ||
import ApiPackage from './definitions/ApiPackage'; | ||
import AstPackage from './ast/AstPackage'; | ||
import DocItemLoader from './DocItemLoader'; | ||
@@ -45,3 +45,3 @@ export declare type ApiErrorHandler = (message: string, fileName: string, lineNumber: number) => void; | ||
* The main entry point for the "api-extractor" utility. The Analyzer object invokes the | ||
* TypeScript Compiler API to analyze a project, and constructs the ApiItem | ||
* TypeScript Compiler API to analyze a project, and constructs the AstItem | ||
* abstract syntax tree. | ||
@@ -54,3 +54,3 @@ * | ||
typeChecker: ts.TypeChecker; | ||
package: ApiPackage; | ||
package: AstPackage; | ||
/** | ||
@@ -57,0 +57,0 @@ * One DocItemLoader is needed per analyzer to look up external API members |
@@ -9,7 +9,7 @@ "use strict"; | ||
var node_core_library_1 = require("@microsoft/node-core-library"); | ||
var ApiPackage_1 = require("./definitions/ApiPackage"); | ||
var AstPackage_1 = require("./ast/AstPackage"); | ||
var DocItemLoader_1 = require("./DocItemLoader"); | ||
/** | ||
* The main entry point for the "api-extractor" utility. The Analyzer object invokes the | ||
* TypeScript Compiler API to analyze a project, and constructs the ApiItem | ||
* TypeScript Compiler API to analyze a project, and constructs the AstItem | ||
* abstract syntax tree. | ||
@@ -64,5 +64,5 @@ * | ||
this._packageFolder = this.packageJsonLookup.tryGetPackageFolder(currentPath); | ||
this.package = new ApiPackage_1.default(this, rootFile); // construct members | ||
this.package = new AstPackage_1.default(this, rootFile); // construct members | ||
this.package.completeInitialization(); // creates ApiDocumentation | ||
this.package.visitTypeReferencesForApiItem(); | ||
this.package.visitTypeReferencesForAstItem(); | ||
}; | ||
@@ -69,0 +69,0 @@ /** |
import Extractor from '../Extractor'; | ||
import ApiStructuredType from '../definitions/ApiStructuredType'; | ||
import ApiEnum from '../definitions/ApiEnum'; | ||
import ApiEnumValue from '../definitions/ApiEnumValue'; | ||
import ApiFunction from '../definitions/ApiFunction'; | ||
import ApiItemVisitor from '../ApiItemVisitor'; | ||
import ApiPackage from '../definitions/ApiPackage'; | ||
import ApiParameter from '../definitions/ApiParameter'; | ||
import ApiMember from '../definitions/ApiMember'; | ||
import ApiNamespace from '../definitions/ApiNamespace'; | ||
import ApiModuleVariable from '../definitions/ApiModuleVariable'; | ||
import AstStructuredType from '../ast/AstStructuredType'; | ||
import AstEnum from '../ast/AstEnum'; | ||
import AstEnumValue from '../ast/AstEnumValue'; | ||
import AstFunction from '../ast/AstFunction'; | ||
import AstItemVisitor from './AstItemVisitor'; | ||
import AstPackage from '../ast/AstPackage'; | ||
import AstParameter from '../ast/AstParameter'; | ||
import AstMember from '../ast/AstMember'; | ||
import AstNamespace from '../ast/AstNamespace'; | ||
import AstModuleVariable from '../ast/AstModuleVariable'; | ||
import IndentedWriter from '../IndentedWriter'; | ||
@@ -24,3 +24,3 @@ /** | ||
*/ | ||
export default class ApiFileGenerator extends ApiItemVisitor { | ||
export default class ApiFileGenerator extends AstItemVisitor { | ||
protected _indentedWriter: IndentedWriter; | ||
@@ -49,11 +49,11 @@ /** | ||
generateApiFileContent(extractor: Extractor): string; | ||
protected visitApiStructuredType(apiStructuredType: ApiStructuredType): void; | ||
protected visitApiEnum(apiEnum: ApiEnum): void; | ||
protected visitApiEnumValue(apiEnumValue: ApiEnumValue): void; | ||
protected visitApiPackage(apiPackage: ApiPackage): void; | ||
protected visitApiNamespace(apiNamespace: ApiNamespace): void; | ||
protected visitApiModuleVariable(apiModuleVariable: ApiModuleVariable): void; | ||
protected visitApiMember(apiMember: ApiMember): void; | ||
protected visitApiFunction(apiFunction: ApiFunction): void; | ||
protected visitApiParam(apiParam: ApiParameter): void; | ||
protected visitAstStructuredType(astStructuredType: AstStructuredType): void; | ||
protected visitAstEnum(astEnum: AstEnum): void; | ||
protected visitAstEnumValue(astEnumValue: AstEnumValue): void; | ||
protected visitAstPackage(astPackage: AstPackage): void; | ||
protected visitAstNamespace(astNamespace: AstNamespace): void; | ||
protected visitAstModuleVariable(astModuleVariable: AstModuleVariable): void; | ||
protected visitAstMember(astMember: AstMember): void; | ||
protected visitAstFunction(astFunction: AstFunction): void; | ||
protected visitApiParam(astParam: AstParameter): void; | ||
/** | ||
@@ -64,5 +64,5 @@ * Writes a synopsis of the AEDoc comments, which indicates the release tag, | ||
*/ | ||
private _writeAedocSynopsis(apiItem); | ||
private _writeWarnings(apiItem); | ||
private _writeAedocSynopsis(astItem); | ||
private _writeWarnings(astItem); | ||
private _writeLinesAsComments(lines); | ||
} |
@@ -16,7 +16,7 @@ "use strict"; | ||
var fs = require("fs"); | ||
var ApiItem_1 = require("../definitions/ApiItem"); | ||
var ApiItemVisitor_1 = require("../ApiItemVisitor"); | ||
var ApiPackage_1 = require("../definitions/ApiPackage"); | ||
var AstItem_1 = require("../ast/AstItem"); | ||
var AstItemVisitor_1 = require("./AstItemVisitor"); | ||
var AstPackage_1 = require("../ast/AstPackage"); | ||
var IndentedWriter_1 = require("../IndentedWriter"); | ||
var ApiDocumentation_1 = require("../definitions/ApiDocumentation"); | ||
var ReleaseTag_1 = require("../aedoc/ReleaseTag"); | ||
/** | ||
@@ -70,6 +70,6 @@ * For a library such as "example-package", ApiFileGenerator generates the "example-package.api.ts" | ||
}; | ||
ApiFileGenerator.prototype.visitApiStructuredType = function (apiStructuredType) { | ||
ApiFileGenerator.prototype.visitAstStructuredType = function (astStructuredType) { | ||
var _this = this; | ||
var declarationLine = apiStructuredType.getDeclarationLine(); | ||
if (apiStructuredType.documentation.preapproved) { | ||
var declarationLine = astStructuredType.getDeclarationLine(); | ||
if (astStructuredType.documentation.preapproved) { | ||
this._indentedWriter.writeLine('// @internal (preapproved)'); | ||
@@ -80,13 +80,13 @@ this._indentedWriter.writeLine(declarationLine + ' {'); | ||
} | ||
if (apiStructuredType.kind !== ApiItem_1.ApiItemKind.TypeLiteral) { | ||
this._writeAedocSynopsis(apiStructuredType); | ||
if (astStructuredType.kind !== AstItem_1.AstItemKind.TypeLiteral) { | ||
this._writeAedocSynopsis(astStructuredType); | ||
} | ||
this._indentedWriter.writeLine(declarationLine + ' {'); | ||
this._indentedWriter.indentScope(function () { | ||
if (apiStructuredType.kind === ApiItem_1.ApiItemKind.TypeLiteral) { | ||
if (astStructuredType.kind === AstItem_1.AstItemKind.TypeLiteral) { | ||
// Type literals don't have normal JSDoc. Write only the warnings, | ||
// and put them after the '{' since the declaration is nested. | ||
_this._writeWarnings(apiStructuredType); | ||
_this._writeWarnings(astStructuredType); | ||
} | ||
for (var _i = 0, _a = apiStructuredType.getSortedMemberItems(); _i < _a.length; _i++) { | ||
for (var _i = 0, _a = astStructuredType.getSortedMemberItems(); _i < _a.length; _i++) { | ||
var member = _a[_i]; | ||
@@ -99,8 +99,8 @@ _this.visit(member); | ||
}; | ||
ApiFileGenerator.prototype.visitApiEnum = function (apiEnum) { | ||
ApiFileGenerator.prototype.visitAstEnum = function (astEnum) { | ||
var _this = this; | ||
this._writeAedocSynopsis(apiEnum); | ||
this._indentedWriter.writeLine("enum " + apiEnum.name + " {"); | ||
this._writeAedocSynopsis(astEnum); | ||
this._indentedWriter.writeLine("enum " + astEnum.name + " {"); | ||
this._indentedWriter.indentScope(function () { | ||
var members = apiEnum.getSortedMemberItems(); | ||
var members = astEnum.getSortedMemberItems(); | ||
for (var i = 0; i < members.length; ++i) { | ||
@@ -113,25 +113,25 @@ _this.visit(members[i]); | ||
}; | ||
ApiFileGenerator.prototype.visitApiEnumValue = function (apiEnumValue) { | ||
this._writeAedocSynopsis(apiEnumValue); | ||
this._indentedWriter.write(apiEnumValue.getDeclarationLine()); | ||
ApiFileGenerator.prototype.visitAstEnumValue = function (astEnumValue) { | ||
this._writeAedocSynopsis(astEnumValue); | ||
this._indentedWriter.write(astEnumValue.getDeclarationLine()); | ||
}; | ||
ApiFileGenerator.prototype.visitApiPackage = function (apiPackage) { | ||
for (var _i = 0, _a = apiPackage.getSortedMemberItems(); _i < _a.length; _i++) { | ||
var apiItem = _a[_i]; | ||
this.visit(apiItem); | ||
ApiFileGenerator.prototype.visitAstPackage = function (astPackage) { | ||
for (var _i = 0, _a = astPackage.getSortedMemberItems(); _i < _a.length; _i++) { | ||
var astItem = _a[_i]; | ||
this.visit(astItem); | ||
this._indentedWriter.writeLine(); | ||
this._indentedWriter.writeLine(); | ||
} | ||
this._writeAedocSynopsis(apiPackage); | ||
this._writeAedocSynopsis(astPackage); | ||
}; | ||
ApiFileGenerator.prototype.visitApiNamespace = function (apiNamespace) { | ||
ApiFileGenerator.prototype.visitAstNamespace = function (astNamespace) { | ||
var _this = this; | ||
this._writeAedocSynopsis(apiNamespace); | ||
// We have decided to call the apiNamespace a 'module' in our | ||
this._writeAedocSynopsis(astNamespace); | ||
// We have decided to call the astNamespace a 'module' in our | ||
// public API documentation. | ||
this._indentedWriter.writeLine("module " + apiNamespace.name + " {"); | ||
this._indentedWriter.writeLine("module " + astNamespace.name + " {"); | ||
this._indentedWriter.indentScope(function () { | ||
for (var _i = 0, _a = apiNamespace.getSortedMemberItems(); _i < _a.length; _i++) { | ||
var apiItem = _a[_i]; | ||
_this.visit(apiItem); | ||
for (var _i = 0, _a = astNamespace.getSortedMemberItems(); _i < _a.length; _i++) { | ||
var astItem = _a[_i]; | ||
_this.visit(astItem); | ||
_this._indentedWriter.writeLine(); | ||
@@ -143,22 +143,22 @@ _this._indentedWriter.writeLine(); | ||
}; | ||
ApiFileGenerator.prototype.visitApiModuleVariable = function (apiModuleVariable) { | ||
this._writeAedocSynopsis(apiModuleVariable); | ||
this._indentedWriter.write(apiModuleVariable.name + ": " + apiModuleVariable.type + " = " + apiModuleVariable.value + ";"); | ||
ApiFileGenerator.prototype.visitAstModuleVariable = function (astModuleVariable) { | ||
this._writeAedocSynopsis(astModuleVariable); | ||
this._indentedWriter.write(astModuleVariable.name + ": " + astModuleVariable.type + " = " + astModuleVariable.value + ";"); | ||
}; | ||
ApiFileGenerator.prototype.visitApiMember = function (apiMember) { | ||
if (apiMember.documentation) { | ||
this._writeAedocSynopsis(apiMember); | ||
ApiFileGenerator.prototype.visitAstMember = function (astMember) { | ||
if (astMember.documentation) { | ||
this._writeAedocSynopsis(astMember); | ||
} | ||
this._indentedWriter.write(apiMember.getDeclarationLine()); | ||
if (apiMember.typeLiteral) { | ||
this._indentedWriter.write(astMember.getDeclarationLine()); | ||
if (astMember.typeLiteral) { | ||
this._insideTypeLiteral += 1; | ||
this.visit(apiMember.typeLiteral); | ||
this.visit(astMember.typeLiteral); | ||
this._insideTypeLiteral -= 1; | ||
} | ||
}; | ||
ApiFileGenerator.prototype.visitApiFunction = function (apiFunction) { | ||
this._writeAedocSynopsis(apiFunction); | ||
this._indentedWriter.write(apiFunction.getDeclarationLine()); | ||
ApiFileGenerator.prototype.visitAstFunction = function (astFunction) { | ||
this._writeAedocSynopsis(astFunction); | ||
this._indentedWriter.write(astFunction.getDeclarationLine()); | ||
}; | ||
ApiFileGenerator.prototype.visitApiParam = function (apiParam) { | ||
ApiFileGenerator.prototype.visitApiParam = function (astParam) { | ||
throw Error('Not Implemented'); | ||
@@ -171,6 +171,6 @@ }; | ||
*/ | ||
ApiFileGenerator.prototype._writeAedocSynopsis = function (apiItem) { | ||
this._writeWarnings(apiItem); | ||
ApiFileGenerator.prototype._writeAedocSynopsis = function (astItem) { | ||
this._writeWarnings(astItem); | ||
var lines = []; | ||
if (apiItem instanceof ApiPackage_1.default && !apiItem.documentation.summary.length) { | ||
if (astItem instanceof AstPackage_1.default && !astItem.documentation.summary.length) { | ||
lines.push('(No packageDescription for this package)'); | ||
@@ -180,13 +180,13 @@ } | ||
var footer = ''; | ||
switch (apiItem.documentation.releaseTag) { | ||
case ApiDocumentation_1.ReleaseTag.Internal: | ||
switch (astItem.documentation.releaseTag) { | ||
case ReleaseTag_1.ReleaseTag.Internal: | ||
footer += '@internal'; | ||
break; | ||
case ApiDocumentation_1.ReleaseTag.Alpha: | ||
case ReleaseTag_1.ReleaseTag.Alpha: | ||
footer += '@alpha'; | ||
break; | ||
case ApiDocumentation_1.ReleaseTag.Beta: | ||
case ReleaseTag_1.ReleaseTag.Beta: | ||
footer += '@beta'; | ||
break; | ||
case ApiDocumentation_1.ReleaseTag.Public: | ||
case ReleaseTag_1.ReleaseTag.Public: | ||
footer += '@public'; | ||
@@ -197,3 +197,3 @@ break; | ||
// this ensures it has contents before adding '@deprecated' | ||
if (apiItem.documentation.deprecatedMessage.length > 0) { | ||
if (astItem.documentation.deprecatedMessage.length > 0) { | ||
if (footer) { | ||
@@ -205,3 +205,3 @@ footer += ' '; | ||
// If we are anywhere inside a TypeLiteral, _insideTypeLiteral is greater than 0 | ||
if (this._insideTypeLiteral === 0 && apiItem.needsDocumentation) { | ||
if (this._insideTypeLiteral === 0 && astItem.needsDocumentation) { | ||
if (footer) { | ||
@@ -218,4 +218,4 @@ footer += ' '; | ||
}; | ||
ApiFileGenerator.prototype._writeWarnings = function (apiItem) { | ||
var lines = apiItem.warnings.map(function (x) { return 'WARNING: ' + x; }); | ||
ApiFileGenerator.prototype._writeWarnings = function (astItem) { | ||
var lines = astItem.warnings.map(function (x) { return 'WARNING: ' + x; }); | ||
this._writeLinesAsComments(lines); | ||
@@ -232,5 +232,5 @@ }; | ||
return ApiFileGenerator; | ||
}(ApiItemVisitor_1.default)); | ||
}(AstItemVisitor_1.default)); | ||
exports.default = ApiFileGenerator; | ||
//# sourceMappingURL=ApiFileGenerator.js.map |
import { JsonSchema } from '@microsoft/node-core-library'; | ||
import Extractor from '../Extractor'; | ||
import ApiStructuredType from '../definitions/ApiStructuredType'; | ||
import ApiEnum from '../definitions/ApiEnum'; | ||
import ApiEnumValue from '../definitions/ApiEnumValue'; | ||
import ApiFunction from '../definitions/ApiFunction'; | ||
import ApiItem from '../definitions/ApiItem'; | ||
import ApiItemVisitor from '../ApiItemVisitor'; | ||
import ApiPackage from '../definitions/ApiPackage'; | ||
import ApiParameter from '../definitions/ApiParameter'; | ||
import ApiProperty from '../definitions/ApiProperty'; | ||
import ApiMember from '../definitions/ApiMember'; | ||
import ApiNamespace from '../definitions/ApiNamespace'; | ||
import ApiModuleVariable from '../definitions/ApiModuleVariable'; | ||
import ApiMethod from '../definitions/ApiMethod'; | ||
import AstStructuredType from '../ast/AstStructuredType'; | ||
import AstEnum from '../ast/AstEnum'; | ||
import AstEnumValue from '../ast/AstEnumValue'; | ||
import AstFunction from '../ast/AstFunction'; | ||
import AstItem from '../ast/AstItem'; | ||
import AstItemVisitor from './AstItemVisitor'; | ||
import AstPackage from '../ast/AstPackage'; | ||
import AstParameter from '../ast/AstParameter'; | ||
import AstProperty from '../ast/AstProperty'; | ||
import AstMember from '../ast/AstMember'; | ||
import AstNamespace from '../ast/AstNamespace'; | ||
import AstModuleVariable from '../ast/AstModuleVariable'; | ||
import AstMethod from '../ast/AstMethod'; | ||
/** | ||
* For a library such as "example-package", ApiFileGenerator generates the "example-package.api.ts" | ||
* report which is used to detect API changes. The output is pseudocode whose syntax is similar | ||
* but not identical to a "*.d.ts" typings file. The output file is designed to be committed to | ||
* Git with a branch policy that will trigger an API review workflow whenever the file contents | ||
* have changed. For example, the API file indicates *whether* a class has been documented, | ||
* but it does not include the documentation text (since minor text changes should not require | ||
* an API review). | ||
* For a library such as "example-package", ApiFileGenerator generates the "example-package.api.json" | ||
* file which represents the API surface for that package. This file should be published as part | ||
* of the library's NPM package. API Extractor will read this file later when it is analyzing | ||
* another project that consumes the library. (Otherwise, API Extractor would have to re-analyze all | ||
* the *.d.ts files, which would be bad because the compiler definitions might not be available for | ||
* a published package, or the results of the analysis might be different somehow.) Documentation | ||
* tools such as api-documenter can also use the *.api.json files. | ||
* | ||
* @public | ||
*/ | ||
export default class ApiJsonGenerator extends ApiItemVisitor { | ||
export default class ApiJsonGenerator extends AstItemVisitor { | ||
private static _methodCounter; | ||
@@ -38,14 +38,14 @@ private static _MEMBERS_KEY; | ||
writeJsonFile(reportFilename: string, extractor: Extractor): void; | ||
protected visit(apiItem: ApiItem, refObject?: Object): void; | ||
protected visitApiStructuredType(apiStructuredType: ApiStructuredType, refObject?: Object): void; | ||
protected visitApiEnum(apiEnum: ApiEnum, refObject?: Object): void; | ||
protected visitApiEnumValue(apiEnumValue: ApiEnumValue, refObject?: Object): void; | ||
protected visitApiFunction(apiFunction: ApiFunction, refObject?: Object): void; | ||
protected visitApiPackage(apiPackage: ApiPackage, refObject?: Object): void; | ||
protected visitApiNamespace(apiNamespace: ApiNamespace, refObject?: Object): void; | ||
protected visitApiMember(apiMember: ApiMember, refObject?: Object): void; | ||
protected visitApiProperty(apiProperty: ApiProperty, refObject?: Object): void; | ||
protected visitApiModuleVariable(apiModuleVariable: ApiModuleVariable, refObject?: Object): void; | ||
protected visitApiMethod(apiMethod: ApiMethod, refObject?: Object): void; | ||
protected visitApiParam(apiParam: ApiParameter, refObject?: Object): void; | ||
protected visit(astItem: AstItem, refObject?: Object): void; | ||
protected visitAstStructuredType(astStructuredType: AstStructuredType, refObject?: Object): void; | ||
protected visitAstEnum(astEnum: AstEnum, refObject?: Object): void; | ||
protected visitAstEnumValue(astEnumValue: AstEnumValue, refObject?: Object): void; | ||
protected visitAstFunction(astFunction: AstFunction, refObject?: Object): void; | ||
protected visitAstPackage(astPackage: AstPackage, refObject?: Object): void; | ||
protected visitAstNamespace(astNamespace: AstNamespace, refObject?: Object): void; | ||
protected visitAstMember(astMember: AstMember, refObject?: Object): void; | ||
protected visitAstProperty(astProperty: AstProperty, refObject?: Object): void; | ||
protected visitAstModuleVariable(astModuleVariable: AstModuleVariable, refObject?: Object): void; | ||
protected visitAstMethod(astMethod: AstMethod, refObject?: Object): void; | ||
protected visitApiParam(astParam: AstParameter, refObject?: Object): void; | ||
} |
@@ -19,15 +19,15 @@ "use strict"; | ||
var node_core_library_1 = require("@microsoft/node-core-library"); | ||
var ApiItem_1 = require("../definitions/ApiItem"); | ||
var ApiItemVisitor_1 = require("../ApiItemVisitor"); | ||
var ApiMember_1 = require("../definitions/ApiMember"); | ||
var ApiDocumentation_1 = require("../definitions/ApiDocumentation"); | ||
var ApiJsonFile_1 = require("./ApiJsonFile"); | ||
var AstItem_1 = require("../ast/AstItem"); | ||
var AstItemVisitor_1 = require("./AstItemVisitor"); | ||
var AstMember_1 = require("../ast/AstMember"); | ||
var ReleaseTag_1 = require("../aedoc/ReleaseTag"); | ||
var ApiJsonFile_1 = require("../api/ApiJsonFile"); | ||
/** | ||
* For a library such as "example-package", ApiFileGenerator generates the "example-package.api.ts" | ||
* report which is used to detect API changes. The output is pseudocode whose syntax is similar | ||
* but not identical to a "*.d.ts" typings file. The output file is designed to be committed to | ||
* Git with a branch policy that will trigger an API review workflow whenever the file contents | ||
* have changed. For example, the API file indicates *whether* a class has been documented, | ||
* but it does not include the documentation text (since minor text changes should not require | ||
* an API review). | ||
* For a library such as "example-package", ApiFileGenerator generates the "example-package.api.json" | ||
* file which represents the API surface for that package. This file should be published as part | ||
* of the library's NPM package. API Extractor will read this file later when it is analyzing | ||
* another project that consumes the library. (Otherwise, API Extractor would have to re-analyze all | ||
* the *.d.ts files, which would be bad because the compiler definitions might not be available for | ||
* a published package, or the results of the analysis might be different somehow.) Documentation | ||
* tools such as api-documenter can also use the *.api.json files. | ||
* | ||
@@ -49,3 +49,3 @@ * @public | ||
if (!ApiJsonGenerator._jsonSchema) { | ||
ApiJsonGenerator._jsonSchema = node_core_library_1.JsonSchema.fromFile(path.join(__dirname, '../schemas/api-json-schema.json')); | ||
ApiJsonGenerator._jsonSchema = node_core_library_1.JsonSchema.fromFile(path.join(__dirname, '../api/api-json.schema.json')); | ||
} | ||
@@ -71,7 +71,7 @@ return ApiJsonGenerator._jsonSchema; | ||
// @override | ||
ApiJsonGenerator.prototype.visit = function (apiItem, refObject) { | ||
switch (apiItem.documentation.releaseTag) { | ||
case ApiDocumentation_1.ReleaseTag.None: | ||
case ApiDocumentation_1.ReleaseTag.Beta: | ||
case ApiDocumentation_1.ReleaseTag.Public: | ||
ApiJsonGenerator.prototype.visit = function (astItem, refObject) { | ||
switch (astItem.documentation.releaseTag) { | ||
case ReleaseTag_1.ReleaseTag.None: | ||
case ReleaseTag_1.ReleaseTag.Beta: | ||
case ReleaseTag_1.ReleaseTag.Public: | ||
break; | ||
@@ -81,24 +81,24 @@ default: | ||
} | ||
_super.prototype.visit.call(this, apiItem, refObject); | ||
_super.prototype.visit.call(this, astItem, refObject); | ||
}; | ||
ApiJsonGenerator.prototype.visitApiStructuredType = function (apiStructuredType, refObject) { | ||
if (!apiStructuredType.supportedName) { | ||
ApiJsonGenerator.prototype.visitAstStructuredType = function (astStructuredType, refObject) { | ||
if (!astStructuredType.supportedName) { | ||
return; | ||
} | ||
var kind = apiStructuredType.kind === ApiItem_1.ApiItemKind.Class ? ApiJsonFile_1.default.convertKindToJson(ApiItem_1.ApiItemKind.Class) : | ||
apiStructuredType.kind === ApiItem_1.ApiItemKind.Interface ? | ||
ApiJsonFile_1.default.convertKindToJson(ApiItem_1.ApiItemKind.Interface) : ''; | ||
var kind = astStructuredType.kind === AstItem_1.AstItemKind.Class ? ApiJsonFile_1.default.convertKindToJson(AstItem_1.AstItemKind.Class) : | ||
astStructuredType.kind === AstItem_1.AstItemKind.Interface ? | ||
ApiJsonFile_1.default.convertKindToJson(AstItem_1.AstItemKind.Interface) : ''; | ||
var structureNode = { | ||
kind: kind, | ||
extends: apiStructuredType.extends || '', | ||
implements: apiStructuredType.implements || '', | ||
typeParameters: apiStructuredType.typeParameters || [], | ||
deprecatedMessage: apiStructuredType.documentation.deprecatedMessage || [], | ||
summary: apiStructuredType.documentation.summary || [], | ||
remarks: apiStructuredType.documentation.remarks || [], | ||
isBeta: apiStructuredType.documentation.releaseTag === ApiDocumentation_1.ReleaseTag.Beta | ||
extends: astStructuredType.extends || '', | ||
implements: astStructuredType.implements || '', | ||
typeParameters: astStructuredType.typeParameters || [], | ||
deprecatedMessage: astStructuredType.documentation.deprecatedMessage || [], | ||
summary: astStructuredType.documentation.summary || [], | ||
remarks: astStructuredType.documentation.remarks || [], | ||
isBeta: astStructuredType.documentation.releaseTag === ReleaseTag_1.ReleaseTag.Beta | ||
}; | ||
refObject[apiStructuredType.name] = structureNode; | ||
refObject[astStructuredType.name] = structureNode; | ||
ApiJsonGenerator._methodCounter = 0; | ||
var members = apiStructuredType.getSortedMemberItems(); | ||
var members = astStructuredType.getSortedMemberItems(); | ||
if (members && members.length) { | ||
@@ -108,9 +108,9 @@ var membersNode = {}; | ||
for (var _i = 0, members_1 = members; _i < members_1.length; _i++) { | ||
var apiItem = members_1[_i]; | ||
this.visit(apiItem, membersNode); | ||
var astItem = members_1[_i]; | ||
this.visit(astItem, membersNode); | ||
} | ||
} | ||
}; | ||
ApiJsonGenerator.prototype.visitApiEnum = function (apiEnum, refObject) { | ||
if (!apiEnum.supportedName) { | ||
ApiJsonGenerator.prototype.visitAstEnum = function (astEnum, refObject) { | ||
if (!astEnum.supportedName) { | ||
return; | ||
@@ -120,142 +120,142 @@ } | ||
var enumNode = { | ||
kind: ApiJsonFile_1.default.convertKindToJson(apiEnum.kind), | ||
kind: ApiJsonFile_1.default.convertKindToJson(astEnum.kind), | ||
values: valuesNode, | ||
deprecatedMessage: apiEnum.documentation.deprecatedMessage || [], | ||
summary: apiEnum.documentation.summary || [], | ||
remarks: apiEnum.documentation.remarks || [], | ||
isBeta: apiEnum.documentation.releaseTag === ApiDocumentation_1.ReleaseTag.Beta | ||
deprecatedMessage: astEnum.documentation.deprecatedMessage || [], | ||
summary: astEnum.documentation.summary || [], | ||
remarks: astEnum.documentation.remarks || [], | ||
isBeta: astEnum.documentation.releaseTag === ReleaseTag_1.ReleaseTag.Beta | ||
}; | ||
refObject[apiEnum.name] = enumNode; | ||
for (var _i = 0, _a = apiEnum.getSortedMemberItems(); _i < _a.length; _i++) { | ||
var apiItem = _a[_i]; | ||
this.visit(apiItem, valuesNode); | ||
refObject[astEnum.name] = enumNode; | ||
for (var _i = 0, _a = astEnum.getSortedMemberItems(); _i < _a.length; _i++) { | ||
var astItem = _a[_i]; | ||
this.visit(astItem, valuesNode); | ||
} | ||
}; | ||
ApiJsonGenerator.prototype.visitApiEnumValue = function (apiEnumValue, refObject) { | ||
if (!apiEnumValue.supportedName) { | ||
ApiJsonGenerator.prototype.visitAstEnumValue = function (astEnumValue, refObject) { | ||
if (!astEnumValue.supportedName) { | ||
return; | ||
} | ||
var declaration = apiEnumValue.getDeclaration(); | ||
var declaration = astEnumValue.getDeclaration(); | ||
var firstToken = declaration ? declaration.getFirstToken() : undefined; | ||
var lastToken = declaration ? declaration.getLastToken() : undefined; | ||
var value = lastToken && lastToken !== firstToken ? lastToken.getText() : ''; | ||
refObject[apiEnumValue.name] = { | ||
kind: ApiJsonFile_1.default.convertKindToJson(apiEnumValue.kind), | ||
refObject[astEnumValue.name] = { | ||
kind: ApiJsonFile_1.default.convertKindToJson(astEnumValue.kind), | ||
value: value, | ||
deprecatedMessage: apiEnumValue.documentation.deprecatedMessage || [], | ||
summary: apiEnumValue.documentation.summary || [], | ||
remarks: apiEnumValue.documentation.remarks || [], | ||
isBeta: apiEnumValue.documentation.releaseTag === ApiDocumentation_1.ReleaseTag.Beta | ||
deprecatedMessage: astEnumValue.documentation.deprecatedMessage || [], | ||
summary: astEnumValue.documentation.summary || [], | ||
remarks: astEnumValue.documentation.remarks || [], | ||
isBeta: astEnumValue.documentation.releaseTag === ReleaseTag_1.ReleaseTag.Beta | ||
}; | ||
}; | ||
ApiJsonGenerator.prototype.visitApiFunction = function (apiFunction, refObject) { | ||
if (!apiFunction.supportedName) { | ||
ApiJsonGenerator.prototype.visitAstFunction = function (astFunction, refObject) { | ||
if (!astFunction.supportedName) { | ||
return; | ||
} | ||
for (var _i = 0, _a = apiFunction.params; _i < _a.length; _i++) { | ||
for (var _i = 0, _a = astFunction.params; _i < _a.length; _i++) { | ||
var param = _a[_i]; | ||
this.visitApiParam(param, apiFunction.documentation.parameters[param.name]); | ||
this.visitApiParam(param, astFunction.documentation.parameters[param.name]); | ||
} | ||
var returnValueNode = { | ||
type: apiFunction.returnType, | ||
description: apiFunction.documentation.returnsMessage | ||
type: astFunction.returnType, | ||
description: astFunction.documentation.returnsMessage | ||
}; | ||
var newNode = { | ||
kind: ApiJsonFile_1.default.convertKindToJson(apiFunction.kind), | ||
kind: ApiJsonFile_1.default.convertKindToJson(astFunction.kind), | ||
returnValue: returnValueNode, | ||
parameters: apiFunction.documentation.parameters, | ||
deprecatedMessage: apiFunction.documentation.deprecatedMessage || [], | ||
summary: apiFunction.documentation.summary || [], | ||
remarks: apiFunction.documentation.remarks || [], | ||
isBeta: apiFunction.documentation.releaseTag === ApiDocumentation_1.ReleaseTag.Beta | ||
parameters: astFunction.documentation.parameters, | ||
deprecatedMessage: astFunction.documentation.deprecatedMessage || [], | ||
summary: astFunction.documentation.summary || [], | ||
remarks: astFunction.documentation.remarks || [], | ||
isBeta: astFunction.documentation.releaseTag === ReleaseTag_1.ReleaseTag.Beta | ||
}; | ||
refObject[apiFunction.name] = newNode; | ||
refObject[astFunction.name] = newNode; | ||
}; | ||
ApiJsonGenerator.prototype.visitApiPackage = function (apiPackage, refObject) { | ||
ApiJsonGenerator.prototype.visitAstPackage = function (astPackage, refObject) { | ||
/* tslint:disable:no-string-literal */ | ||
refObject['kind'] = ApiJsonFile_1.default.convertKindToJson(apiPackage.kind); | ||
refObject['summary'] = apiPackage.documentation.summary; | ||
refObject['remarks'] = apiPackage.documentation.remarks; | ||
refObject['kind'] = ApiJsonFile_1.default.convertKindToJson(astPackage.kind); | ||
refObject['summary'] = astPackage.documentation.summary; | ||
refObject['remarks'] = astPackage.documentation.remarks; | ||
/* tslint:enable:no-string-literal */ | ||
var membersNode = {}; | ||
refObject[ApiJsonGenerator._EXPORTS_KEY] = membersNode; | ||
for (var _i = 0, _a = apiPackage.getSortedMemberItems(); _i < _a.length; _i++) { | ||
var apiItem = _a[_i]; | ||
this.visit(apiItem, membersNode); | ||
for (var _i = 0, _a = astPackage.getSortedMemberItems(); _i < _a.length; _i++) { | ||
var astItem = _a[_i]; | ||
this.visit(astItem, membersNode); | ||
} | ||
}; | ||
ApiJsonGenerator.prototype.visitApiNamespace = function (apiNamespace, refObject) { | ||
if (!apiNamespace.supportedName) { | ||
ApiJsonGenerator.prototype.visitAstNamespace = function (astNamespace, refObject) { | ||
if (!astNamespace.supportedName) { | ||
return; | ||
} | ||
var membersNode = {}; | ||
for (var _i = 0, _a = apiNamespace.getSortedMemberItems(); _i < _a.length; _i++) { | ||
var apiItem = _a[_i]; | ||
this.visit(apiItem, membersNode); | ||
for (var _i = 0, _a = astNamespace.getSortedMemberItems(); _i < _a.length; _i++) { | ||
var astItem = _a[_i]; | ||
this.visit(astItem, membersNode); | ||
} | ||
var newNode = { | ||
kind: ApiJsonFile_1.default.convertKindToJson(apiNamespace.kind), | ||
deprecatedMessage: apiNamespace.documentation.deprecatedMessage || [], | ||
summary: apiNamespace.documentation.summary || [], | ||
remarks: apiNamespace.documentation.remarks || [], | ||
isBeta: apiNamespace.documentation.releaseTag === ApiDocumentation_1.ReleaseTag.Beta, | ||
kind: ApiJsonFile_1.default.convertKindToJson(astNamespace.kind), | ||
deprecatedMessage: astNamespace.documentation.deprecatedMessage || [], | ||
summary: astNamespace.documentation.summary || [], | ||
remarks: astNamespace.documentation.remarks || [], | ||
isBeta: astNamespace.documentation.releaseTag === ReleaseTag_1.ReleaseTag.Beta, | ||
exports: membersNode | ||
}; | ||
refObject[apiNamespace.name] = newNode; | ||
refObject[astNamespace.name] = newNode; | ||
}; | ||
ApiJsonGenerator.prototype.visitApiMember = function (apiMember, refObject) { | ||
if (!apiMember.supportedName) { | ||
ApiJsonGenerator.prototype.visitAstMember = function (astMember, refObject) { | ||
if (!astMember.supportedName) { | ||
return; | ||
} | ||
refObject[apiMember.name] = 'apiMember-' + apiMember.getDeclaration().kind; | ||
refObject[astMember.name] = 'astMember-' + astMember.getDeclaration().kind; | ||
}; | ||
ApiJsonGenerator.prototype.visitApiProperty = function (apiProperty, refObject) { | ||
if (!apiProperty.supportedName) { | ||
ApiJsonGenerator.prototype.visitAstProperty = function (astProperty, refObject) { | ||
if (!astProperty.supportedName) { | ||
return; | ||
} | ||
if (apiProperty.getDeclaration().kind === ts.SyntaxKind.SetAccessor) { | ||
if (astProperty.getDeclaration().kind === ts.SyntaxKind.SetAccessor) { | ||
return; | ||
} | ||
var newNode = { | ||
kind: ApiJsonFile_1.default.convertKindToJson(apiProperty.kind), | ||
isOptional: !!apiProperty.isOptional, | ||
isReadOnly: !!apiProperty.isReadOnly, | ||
isStatic: !!apiProperty.isStatic, | ||
type: apiProperty.type, | ||
deprecatedMessage: apiProperty.documentation.deprecatedMessage || [], | ||
summary: apiProperty.documentation.summary || [], | ||
remarks: apiProperty.documentation.remarks || [], | ||
isBeta: apiProperty.documentation.releaseTag === ApiDocumentation_1.ReleaseTag.Beta | ||
kind: ApiJsonFile_1.default.convertKindToJson(astProperty.kind), | ||
isOptional: !!astProperty.isOptional, | ||
isReadOnly: !!astProperty.isReadOnly, | ||
isStatic: !!astProperty.isStatic, | ||
type: astProperty.type, | ||
deprecatedMessage: astProperty.documentation.deprecatedMessage || [], | ||
summary: astProperty.documentation.summary || [], | ||
remarks: astProperty.documentation.remarks || [], | ||
isBeta: astProperty.documentation.releaseTag === ReleaseTag_1.ReleaseTag.Beta | ||
}; | ||
refObject[apiProperty.name] = newNode; | ||
refObject[astProperty.name] = newNode; | ||
}; | ||
ApiJsonGenerator.prototype.visitApiModuleVariable = function (apiModuleVariable, refObject) { | ||
ApiJsonGenerator.prototype.visitAstModuleVariable = function (astModuleVariable, refObject) { | ||
var newNode = { | ||
kind: ApiJsonFile_1.default.convertKindToJson(apiModuleVariable.kind), | ||
type: apiModuleVariable.type, | ||
value: apiModuleVariable.value, | ||
deprecatedMessage: apiModuleVariable.documentation.deprecatedMessage || [], | ||
summary: apiModuleVariable.documentation.summary || [], | ||
remarks: apiModuleVariable.documentation.remarks || [], | ||
isBeta: apiModuleVariable.documentation.releaseTag === ApiDocumentation_1.ReleaseTag.Beta | ||
kind: ApiJsonFile_1.default.convertKindToJson(astModuleVariable.kind), | ||
type: astModuleVariable.type, | ||
value: astModuleVariable.value, | ||
deprecatedMessage: astModuleVariable.documentation.deprecatedMessage || [], | ||
summary: astModuleVariable.documentation.summary || [], | ||
remarks: astModuleVariable.documentation.remarks || [], | ||
isBeta: astModuleVariable.documentation.releaseTag === ReleaseTag_1.ReleaseTag.Beta | ||
}; | ||
refObject[apiModuleVariable.name] = newNode; | ||
refObject[astModuleVariable.name] = newNode; | ||
}; | ||
ApiJsonGenerator.prototype.visitApiMethod = function (apiMethod, refObject) { | ||
if (!apiMethod.supportedName) { | ||
ApiJsonGenerator.prototype.visitAstMethod = function (astMethod, refObject) { | ||
if (!astMethod.supportedName) { | ||
return; | ||
} | ||
for (var _i = 0, _a = apiMethod.params; _i < _a.length; _i++) { | ||
for (var _i = 0, _a = astMethod.params; _i < _a.length; _i++) { | ||
var param = _a[_i]; | ||
this.visitApiParam(param, apiMethod.documentation.parameters[param.name]); | ||
this.visitApiParam(param, astMethod.documentation.parameters[param.name]); | ||
} | ||
var newNode; | ||
if (apiMethod.name === '__constructor') { | ||
if (astMethod.name === '__constructor') { | ||
newNode = { | ||
kind: ApiJsonFile_1.default.convertKindToJson(ApiItem_1.ApiItemKind.Constructor), | ||
signature: apiMethod.getDeclarationLine(), | ||
parameters: apiMethod.documentation.parameters, | ||
deprecatedMessage: apiMethod.documentation.deprecatedMessage || [], | ||
summary: apiMethod.documentation.summary || [], | ||
remarks: apiMethod.documentation.remarks || [] | ||
kind: ApiJsonFile_1.default.convertKindToJson(AstItem_1.AstItemKind.Constructor), | ||
signature: astMethod.getDeclarationLine(), | ||
parameters: astMethod.documentation.parameters, | ||
deprecatedMessage: astMethod.documentation.deprecatedMessage || [], | ||
summary: astMethod.documentation.summary || [], | ||
remarks: astMethod.documentation.remarks || [] | ||
}; | ||
@@ -265,29 +265,29 @@ } | ||
var returnValueNode = { | ||
type: apiMethod.returnType, | ||
description: apiMethod.documentation.returnsMessage | ||
type: astMethod.returnType, | ||
description: astMethod.documentation.returnsMessage | ||
}; | ||
newNode = { | ||
kind: ApiJsonFile_1.default.convertKindToJson(apiMethod.kind), | ||
signature: apiMethod.getDeclarationLine(), | ||
accessModifier: apiMethod.accessModifier ? ApiMember_1.AccessModifier[apiMethod.accessModifier].toLowerCase() : '', | ||
isOptional: !!apiMethod.isOptional, | ||
isStatic: !!apiMethod.isStatic, | ||
kind: ApiJsonFile_1.default.convertKindToJson(astMethod.kind), | ||
signature: astMethod.getDeclarationLine(), | ||
accessModifier: astMethod.accessModifier ? AstMember_1.ApiAccessModifier[astMethod.accessModifier].toLowerCase() : '', | ||
isOptional: !!astMethod.isOptional, | ||
isStatic: !!astMethod.isStatic, | ||
returnValue: returnValueNode, | ||
parameters: apiMethod.documentation.parameters, | ||
deprecatedMessage: apiMethod.documentation.deprecatedMessage || [], | ||
summary: apiMethod.documentation.summary || [], | ||
remarks: apiMethod.documentation.remarks || [], | ||
isBeta: apiMethod.documentation.releaseTag === ApiDocumentation_1.ReleaseTag.Beta | ||
parameters: astMethod.documentation.parameters, | ||
deprecatedMessage: astMethod.documentation.deprecatedMessage || [], | ||
summary: astMethod.documentation.summary || [], | ||
remarks: astMethod.documentation.remarks || [], | ||
isBeta: astMethod.documentation.releaseTag === ReleaseTag_1.ReleaseTag.Beta | ||
}; | ||
} | ||
refObject[apiMethod.name] = newNode; | ||
refObject[astMethod.name] = newNode; | ||
}; | ||
ApiJsonGenerator.prototype.visitApiParam = function (apiParam, refObject) { | ||
if (!apiParam.supportedName) { | ||
ApiJsonGenerator.prototype.visitApiParam = function (astParam, refObject) { | ||
if (!astParam.supportedName) { | ||
return; | ||
} | ||
if (refObject) { | ||
refObject.isOptional = apiParam.isOptional; | ||
refObject.isSpread = apiParam.isSpread; | ||
refObject.type = apiParam.type; | ||
refObject.isOptional = astParam.isOptional; | ||
refObject.isSpread = astParam.isSpread; | ||
refObject.type = astParam.type; | ||
} | ||
@@ -300,5 +300,5 @@ }; | ||
return ApiJsonGenerator; | ||
}(ApiItemVisitor_1.default)); | ||
}(AstItemVisitor_1.default)); | ||
exports.default = ApiJsonGenerator; | ||
//# sourceMappingURL=ApiJsonGenerator.js.map |
@@ -5,1 +5,4 @@ export { default as Extractor, IExtractorOptions, IExtractorAnalyzeOptions, ApiErrorHandler } from './Extractor'; | ||
export { default as ExternalApiHelper } from './ExternalApiHelper'; | ||
export * from './api/ApiItem'; | ||
export * from './markup/MarkupElement'; | ||
export * from './markup/OldMarkup'; |
@@ -28,3 +28,3 @@ import * as ts from 'typescript'; | ||
* Throws an exception. Use this only for unexpected errors, as it may ungracefully terminate the process; | ||
* ApiItem.reportError() is generally a better option. | ||
* AstItem.reportError() is generally a better option. | ||
*/ | ||
@@ -31,0 +31,0 @@ static throwUnexpectedSyntaxError(errorNode: ts.Node, message: string): void; |
@@ -87,3 +87,3 @@ "use strict"; | ||
* Throws an exception. Use this only for unexpected errors, as it may ungracefully terminate the process; | ||
* ApiItem.reportError() is generally a better option. | ||
* AstItem.reportError() is generally a better option. | ||
*/ | ||
@@ -90,0 +90,0 @@ PrettyPrinter.throwUnexpectedSyntaxError = function (errorNode, message) { |
@@ -1,11 +0,12 @@ | ||
import ApiItem, { ApiItemKind } from './definitions/ApiItem'; | ||
import { ReleaseTag } from './definitions/ApiDocumentation'; | ||
import { IDocElement, IParam } from './IDocElement'; | ||
import { IDocItem } from './IDocItem'; | ||
import AstItem, { AstItemKind } from './ast/AstItem'; | ||
import { ReleaseTag } from './aedoc/ReleaseTag'; | ||
import { IDocElement } from './markup/OldMarkup'; | ||
import { ApiItem } from './api/ApiItem'; | ||
import { IAedocParameter } from './aedoc/ApiDocumentation'; | ||
/** | ||
* A class to abstract away the difference between an item from our public API that could be | ||
* represented by either an ApiItem or an IDocItem that is retrieved from a JSON file. | ||
* represented by either an AstItem or an ApiItem that is retrieved from a JSON file. | ||
*/ | ||
export default class ResolvedApiItem { | ||
kind: ApiItemKind; | ||
kind: AstItemKind; | ||
summary: IDocElement[]; | ||
@@ -17,20 +18,20 @@ remarks: IDocElement[]; | ||
params: { | ||
[name: string]: IParam; | ||
[name: string]: IAedocParameter; | ||
}; | ||
returnsMessage: IDocElement[]; | ||
/** | ||
* This property will either be an ApiItem or undefined. | ||
* This property will either be an AstItem or undefined. | ||
*/ | ||
apiItem: ApiItem; | ||
astItem: AstItem; | ||
/** | ||
* A function to abstract the construction of a ResolvedApiItem instance | ||
* from an ApiItem. | ||
* from an AstItem. | ||
*/ | ||
static createFromApiItem(apiItem: ApiItem): ResolvedApiItem; | ||
static createFromAstItem(astItem: AstItem): ResolvedApiItem; | ||
/** | ||
* A function to abstract the construction of a ResolvedApiItem instance | ||
* from a JSON object that symbolizes an IDocItem. | ||
* from a JSON object that symbolizes an ApiItem. | ||
*/ | ||
static createFromJson(docItem: IDocItem): ResolvedApiItem; | ||
static createFromJson(docItem: ApiItem): ResolvedApiItem; | ||
private constructor(); | ||
} |
@@ -5,10 +5,10 @@ "use strict"; | ||
Object.defineProperty(exports, "__esModule", { value: true }); | ||
var ApiDocumentation_1 = require("./definitions/ApiDocumentation"); | ||
var ApiJsonFile_1 = require("./generators/ApiJsonFile"); | ||
var ReleaseTag_1 = require("./aedoc/ReleaseTag"); | ||
var ApiJsonFile_1 = require("./api/ApiJsonFile"); | ||
/** | ||
* A class to abstract away the difference between an item from our public API that could be | ||
* represented by either an ApiItem or an IDocItem that is retrieved from a JSON file. | ||
* represented by either an AstItem or an ApiItem that is retrieved from a JSON file. | ||
*/ | ||
var ResolvedApiItem = (function () { | ||
function ResolvedApiItem(kind, summary, remarks, deprecatedMessage, isBeta, params, returnsMessage, releaseTag, apiItem) { | ||
function ResolvedApiItem(kind, summary, remarks, deprecatedMessage, isBeta, params, returnsMessage, releaseTag, astItem) { | ||
this.kind = kind; | ||
@@ -22,14 +22,14 @@ this.summary = summary; | ||
this.releaseTag = releaseTag; | ||
this.apiItem = apiItem; | ||
this.astItem = astItem; | ||
} | ||
/** | ||
* A function to abstract the construction of a ResolvedApiItem instance | ||
* from an ApiItem. | ||
* from an AstItem. | ||
*/ | ||
ResolvedApiItem.createFromApiItem = function (apiItem) { | ||
return new ResolvedApiItem(apiItem.kind, apiItem.documentation.summary, apiItem.documentation.remarks, apiItem.documentation.deprecatedMessage, apiItem.documentation.releaseTag === ApiDocumentation_1.ReleaseTag.Beta, apiItem.documentation.parameters, apiItem.documentation.returnsMessage, apiItem.documentation.releaseTag, apiItem); | ||
ResolvedApiItem.createFromAstItem = function (astItem) { | ||
return new ResolvedApiItem(astItem.kind, astItem.documentation.summary, astItem.documentation.remarks, astItem.documentation.deprecatedMessage, astItem.documentation.releaseTag === ReleaseTag_1.ReleaseTag.Beta, astItem.documentation.parameters, astItem.documentation.returnsMessage, astItem.documentation.releaseTag, astItem); | ||
}; | ||
/** | ||
* A function to abstract the construction of a ResolvedApiItem instance | ||
* from a JSON object that symbolizes an IDocItem. | ||
* from a JSON object that symbolizes an ApiItem. | ||
*/ | ||
@@ -51,3 +51,3 @@ ResolvedApiItem.createFromJson = function (docItem) { | ||
} | ||
return new ResolvedApiItem(ApiJsonFile_1.default.convertJsonToKind(docItem.kind), docItem.summary, docItem.remarks, docItem.deprecatedMessage, docItem.isBeta, parameters, returnsMessage, ApiDocumentation_1.ReleaseTag.Public, undefined); | ||
return new ResolvedApiItem(ApiJsonFile_1.default.convertJsonToKind(docItem.kind), docItem.summary, docItem.remarks, docItem.deprecatedMessage, docItem.isBeta, parameters, returnsMessage, ReleaseTag_1.ReleaseTag.Public, undefined); | ||
}; | ||
@@ -54,0 +54,0 @@ return ResolvedApiItem; |
@@ -22,5 +22,5 @@ "use strict"; | ||
var TestFileComparer_1 = require("../TestFileComparer"); | ||
var ApiDocumentation_1 = require("../definitions/ApiDocumentation"); | ||
var Extractor_1 = require("./../Extractor"); | ||
var Tokenizer_1 = require("./../Tokenizer"); | ||
var ApiDocumentation_1 = require("../aedoc/ApiDocumentation"); | ||
var Extractor_1 = require("../Extractor"); | ||
var Tokenizer_1 = require("../aedoc/Tokenizer"); | ||
var capturedErrors = []; | ||
@@ -70,3 +70,3 @@ function testErrorHandler(message, fileName, lineNumber) { | ||
myDocumentedClass = extractor.package.getSortedMemberItems() | ||
.filter(function (apiItem) { return apiItem.name === 'MyDocumentedClass'; })[0]; | ||
.filter(function (astItem) { return astItem.name === 'MyDocumentedClass'; })[0]; | ||
describe('DocElementParser tests', function () { | ||
@@ -73,0 +73,0 @@ this.timeout(10000); |
{ | ||
"name": "@microsoft/api-extractor", | ||
"version": "3.0.0", | ||
"version": "3.1.0", | ||
"description": "Validate, document, and review the exported API for a TypeScript library", | ||
@@ -30,3 +30,3 @@ "keywords": [ | ||
"dependencies": { | ||
"@microsoft/node-core-library": "~0.2.2", | ||
"@microsoft/node-core-library": "~0.2.3", | ||
"@types/es6-collections": "0.5.29", | ||
@@ -33,0 +33,0 @@ "@types/fs-extra": "0.0.37", |
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
9935
769153