@microsoft/api-extractor
Version:
Analyze the exported API for a TypeScript library and generate reviews, documentation, and .d.ts rollups
218 lines • 9.09 kB
JavaScript
;
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
// See LICENSE in the project root for license information.
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
var desc = Object.getOwnPropertyDescriptor(m, k);
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
desc = { enumerable: true, get: function() { return m[k]; } };
}
Object.defineProperty(o, k2, desc);
}) : (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
o[k2] = m[k];
}));
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
Object.defineProperty(o, "default", { enumerable: true, value: v });
}) : function(o, v) {
o["default"] = v;
});
var __importStar = (this && this.__importStar) || (function () {
var ownKeys = function(o) {
ownKeys = Object.getOwnPropertyNames || function (o) {
var ar = [];
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
return ar;
};
return ownKeys(o);
};
return function (mod) {
if (mod && mod.__esModule) return mod;
var result = {};
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
__setModuleDefault(result, mod);
return result;
};
})();
Object.defineProperty(exports, "__esModule", { value: true });
exports.ExcerptBuilder = void 0;
const ts = __importStar(require("typescript"));
const api_extractor_model_1 = require("@microsoft/api-extractor-model");
const Span_1 = require("../analyzer/Span");
const condenseTokens_1 = require("./condenseTokens");
class ExcerptBuilder {
/**
* Appends a blank line to the `excerptTokens` list.
* @param excerptTokens - The target token list to append to
*/
static addBlankLine(excerptTokens) {
let newlines = '\n\n';
// If the existing text already ended with a newline, then only append one newline
if (excerptTokens.length > 0) {
const previousText = excerptTokens[excerptTokens.length - 1].text;
if (/\n$/.test(previousText)) {
newlines = '\n';
}
}
excerptTokens.push({ kind: api_extractor_model_1.ExcerptTokenKind.Content, text: newlines });
}
/**
* Appends the signature for the specified `AstDeclaration` to the `excerptTokens` list.
* @param excerptTokens - The target token list to append to
* @param nodeTransforms - A list of child nodes whose token ranges we want to capture
*/
static addDeclaration(excerptTokens, astDeclaration, nodeTransforms, referenceGenerator) {
let stopBeforeChildKind = undefined;
switch (astDeclaration.declaration.kind) {
case ts.SyntaxKind.ClassDeclaration:
case ts.SyntaxKind.EnumDeclaration:
case ts.SyntaxKind.InterfaceDeclaration:
// FirstPunctuation = "{"
stopBeforeChildKind = ts.SyntaxKind.FirstPunctuation;
break;
case ts.SyntaxKind.ModuleDeclaration:
// ModuleBlock = the "{ ... }" block
stopBeforeChildKind = ts.SyntaxKind.ModuleBlock;
break;
}
const span = new Span_1.Span(astDeclaration.declaration);
const transformsByNode = new Map();
const captureTokenRanges = [];
for (const nodeTransform of nodeTransforms || []) {
transformsByNode.set(nodeTransform.node, nodeTransform);
if (nodeTransform.captureTokenRange) {
captureTokenRanges.push(nodeTransform.captureTokenRange);
}
}
_buildSpan(excerptTokens, span, {
referenceGenerator: referenceGenerator,
startingNode: span.node,
stopBeforeChildKind,
transformsByNode: transformsByNode,
lastAppendedTokenIsSeparator: false
});
(0, condenseTokens_1.condenseTokens)(excerptTokens, captureTokenRanges);
}
static createEmptyTokenRange() {
return { startIndex: 0, endIndex: 0 };
}
}
exports.ExcerptBuilder = ExcerptBuilder;
/** @returns false if we encountered a token that causes iteration to stop. */
function _buildSpan(excerptTokens, span, state) {
if (span.kind === ts.SyntaxKind.JSDocComment) {
// Discard any comments
return true;
}
// Can this node start a excerpt?
const transform = state.transformsByNode.get(span.node);
let captureTokenRange = undefined;
if (transform) {
captureTokenRange = transform.captureTokenRange;
if (transform.replacementText !== undefined) {
excerptTokens.push({
kind: api_extractor_model_1.ExcerptTokenKind.Content,
text: transform.replacementText
});
state.lastAppendedTokenIsSeparator = false;
if (captureTokenRange) {
captureTokenRange.startIndex = excerptTokens.length;
captureTokenRange.endIndex = captureTokenRange.startIndex + 1;
}
return true;
}
}
let excerptStartIndex = 0;
if (captureTokenRange) {
// We will assign capturedTokenRange.startIndex to be the index of the next token to be appended
excerptStartIndex = excerptTokens.length;
}
if (span.prefix) {
let canonicalReference = undefined;
if (span.kind === ts.SyntaxKind.Identifier) {
const name = span.node;
if (!_isDeclarationName(name)) {
canonicalReference = state.referenceGenerator.getDeclarationReferenceForIdentifier(name);
}
}
if (canonicalReference) {
_appendToken(excerptTokens, api_extractor_model_1.ExcerptTokenKind.Reference, span.prefix, canonicalReference);
}
else {
_appendToken(excerptTokens, api_extractor_model_1.ExcerptTokenKind.Content, span.prefix);
}
state.lastAppendedTokenIsSeparator = false;
}
for (const child of span.children) {
if (span.node === state.startingNode) {
if (state.stopBeforeChildKind && child.kind === state.stopBeforeChildKind) {
// We reached a child whose kind is stopBeforeChildKind, so stop traversing
return false;
}
}
if (!_buildSpan(excerptTokens, child, state)) {
return false;
}
}
if (span.suffix) {
_appendToken(excerptTokens, api_extractor_model_1.ExcerptTokenKind.Content, span.suffix);
state.lastAppendedTokenIsSeparator = false;
}
if (span.separator) {
_appendToken(excerptTokens, api_extractor_model_1.ExcerptTokenKind.Content, span.separator);
state.lastAppendedTokenIsSeparator = true;
}
// Are we building a excerpt? If so, set its range
if (captureTokenRange) {
captureTokenRange.startIndex = excerptStartIndex;
// We will assign capturedTokenRange.startIndex to be the index after the last token
// that was appended so far. However, if the last appended token was a separator, omit
// it from the range.
let excerptEndIndex = excerptTokens.length;
if (state.lastAppendedTokenIsSeparator) {
excerptEndIndex--;
}
captureTokenRange.endIndex = excerptEndIndex;
}
return true;
}
function _appendToken(excerptTokens, excerptTokenKind, text, canonicalReference) {
if (text.length === 0) {
return;
}
const excerptToken = { kind: excerptTokenKind, text: text };
if (canonicalReference !== undefined) {
excerptToken.canonicalReference = canonicalReference.toString();
}
excerptTokens.push(excerptToken);
}
function _isDeclarationName(name) {
return _isDeclaration(name.parent) && name.parent.name === name;
}
function _isDeclaration(node) {
switch (node.kind) {
case ts.SyntaxKind.FunctionDeclaration:
case ts.SyntaxKind.FunctionExpression:
case ts.SyntaxKind.VariableDeclaration:
case ts.SyntaxKind.Parameter:
case ts.SyntaxKind.EnumDeclaration:
case ts.SyntaxKind.ClassDeclaration:
case ts.SyntaxKind.ClassExpression:
case ts.SyntaxKind.ModuleDeclaration:
case ts.SyntaxKind.MethodDeclaration:
case ts.SyntaxKind.MethodSignature:
case ts.SyntaxKind.PropertyDeclaration:
case ts.SyntaxKind.PropertySignature:
case ts.SyntaxKind.GetAccessor:
case ts.SyntaxKind.SetAccessor:
case ts.SyntaxKind.InterfaceDeclaration:
case ts.SyntaxKind.TypeAliasDeclaration:
case ts.SyntaxKind.TypeParameter:
case ts.SyntaxKind.EnumMember:
case ts.SyntaxKind.BindingElement:
return true;
default:
return false;
}
}
//# sourceMappingURL=ExcerptBuilder.js.map