@microsoft/api-extractor/lib/generators/ApiFileGenerator.d.ts

Validate, document, and review the exported API for a TypeScript library

import { ExtractorContext } from '../ExtractorContext';
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 AstMember from '../ast/AstMember';
import AstNamespace from '../ast/AstNamespace';
import AstModuleVariable from '../ast/AstModuleVariable';
import IndentedWriter from '../IndentedWriter';
/**
 * 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).
 *
 * @public
 */
export default class ApiFileGenerator extends AstItemVisitor {
    protected _indentedWriter: IndentedWriter;
    /**
     * We don't want to require documentation for any properties that occur
     * anywhere within a TypeLiteral. If this value is above 0, then we are
     * visiting something within a TypeLiteral.
     */
    private _insideTypeLiteral;
    /**
     * Compares the contents of two API files that were created using ApiFileGenerator,
     * and returns true if they are equivalent.  Note that these files are not normally edited
     * by a human; the "equivalence" comparison here is intended to ignore spurious changes that
     * might be introduced by a tool, e.g. Git newline normalization or an editor that strips
     * whitespace when saving.
     */
    static areEquivalentApiFileContents(actualFileContent: string, expectedFileContent: string): boolean;
    /**
     * Generates the report and writes it to disk.
     *
     * @param reportFilename - The output filename
     * @param analyzer       - An Analyzer object representing the input project.
     */
    writeApiFile(reportFilename: string, context: ExtractorContext): void;
    generateApiFileContent(context: ExtractorContext): string;
    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;
    /**
     * Writes a synopsis of the AEDoc comments, which indicates the release tag,
     * whether the item has been documented, and any warnings that were detected
     * by the analysis.
     */
    private _writeAedocSynopsis(astItem);
    private _writeWarnings(astItem);
    private _writeLinesAsComments(lines);
}