Secure your code as it's written. Use Snyk Code to scan source code in minutes - no build needed - and fix issues immediately.
/**
* This is the original TSDoc comment parsed from the source code.
* It may be modified (or constructed artificially) by the DocCommentEnhancer.
*/
public tsdocComment: tsdoc.DocComment | undefined = undefined;
/**
* The ParserContext from when the TSDoc comment was parsed from the source code.
* If the source code did not contain a doc comment, then this will be undefined.
*/
public tsdocParserContext: tsdoc.ParserContext | undefined = undefined;
/**
* This is the release tag that was explicitly specified in the original doc comment, if any.
*/
public declaredReleaseTag: ReleaseTag = ReleaseTag.None;
/**
* The "effective" release tag is a normalized value that is based on `declaredReleaseTag`,
* but may be inherited from a parent, or corrected if the declared value was somehow invalid.
* When actually trimming .d.ts files or generating docs, API Extractor uses the "effective" value
* instead of the "declared" value.
*/
public effectiveReleaseTag: ReleaseTag = ReleaseTag.None;
// NOTE: In the future, the Collector may infer or error-correct some of these states.
// Generators should rely on these instead of tsdocComment.modifierTagSet.
public isEventProperty: boolean = false;
public isOverride: boolean = false;
public isSealed: boolean = false;
public isVirtual: boolean = false;
stringWriter.writeLine(`/// `);
}
for (const libDirectiveReference of collector.dtsLibReferenceDirectives) {
stringWriter.writeLine(`/// `);
}
// Emit the imports
for (const entity of collector.entities) {
if (entity.astEntity instanceof AstImport) {
const astImport: AstImport = entity.astEntity;
// For example, if the imported API comes from an external package that supports AEDoc,
// and it was marked as `@internal`, then don't emit it.
const symbolMetadata: SymbolMetadata | undefined = collector.tryFetchMetadataForAstEntity(astImport);
const releaseTag: ReleaseTag = symbolMetadata ? symbolMetadata.releaseTag : ReleaseTag.None;
if (this._shouldIncludeReleaseTag(releaseTag, dtsKind)) {
DtsEmitHelpers.emitImport(stringWriter, entity, astImport);
}
}
}
// Emit the regular declarations
for (const entity of collector.entities) {
const symbolMetadata: SymbolMetadata | undefined = collector.tryFetchMetadataForAstEntity(
entity.astEntity
);
const releaseTag: ReleaseTag = symbolMetadata ? symbolMetadata.releaseTag : ReleaseTag.None;
if (!this._shouldIncludeReleaseTag(releaseTag, dtsKind)) {
if (!collector.extractorConfig.omitTrimmingComments) {
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
// See LICENSE in the project root for license information.
import { ReleaseTag } from '@microsoft/api-extractor-model';
export class SymbolMetadata {
public releaseTag: ReleaseTag = ReleaseTag.None;
// If true, then it would be redundant to show this release tag
public releaseTagSameAsParent: boolean = false;
}
private static _shouldIncludeReleaseTag(releaseTag: ReleaseTag, dtsKind: DtsRollupKind): boolean {
switch (dtsKind) {
case DtsRollupKind.InternalRelease:
return true;
case DtsRollupKind.BetaRelease:
// NOTE: If the release tag is "None", then we don't have enough information to trim it
return (
releaseTag === ReleaseTag.Beta || releaseTag === ReleaseTag.Public || releaseTag === ReleaseTag.None
);
case DtsRollupKind.PublicRelease:
return releaseTag === ReleaseTag.Public || releaseTag === ReleaseTag.None;
}
throw new Error(`${DtsRollupKind[dtsKind]} is not implemented`);
}
}
private static _getAedocSynopsis(collector: Collector, astDeclaration: AstDeclaration,
messagesToReport: ExtractorMessage[]): string {
const stringWriter: StringWriter = new StringWriter();
for (const message of messagesToReport) {
ApiReportGenerator._writeLineAsComments(stringWriter, 'Warning: ' + message.formatMessageWithoutLocation());
}
const footerParts: string[] = [];
const declarationMetadata: DeclarationMetadata = collector.fetchMetadata(astDeclaration);
if (!declarationMetadata.releaseTagSameAsParent) {
if (declarationMetadata.effectiveReleaseTag !== ReleaseTag.None) {
footerParts.push(ReleaseTag.getTagName(declarationMetadata.effectiveReleaseTag));
}
}
if (declarationMetadata.isSealed) {
footerParts.push('@sealed');
}
if (declarationMetadata.isVirtual) {
footerParts.push('@virtual');
}
if (declarationMetadata.isOverride) {
footerParts.push('@override');
}