@microsoft/api-extractor/lib/ast/AstItem.d.ts

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

import * as ts from 'typescript';
import { ExtractorContext } from '../ExtractorContext';
import { ApiDocumentation } from '../aedoc/ApiDocumentation';
import { MarkupElement } from '../markup/MarkupElement';
import { ReleaseTag } from '../aedoc/ReleaseTag';
import { AstItemContainer } from './AstItemContainer';
/**
 * Indicates the type of definition represented by a AstItem object.
 */
export declare enum AstItemKind {
    /**
      * A TypeScript class.
      */
    Class = 0,
    /**
      * A TypeScript enum.
      */
    Enum = 1,
    /**
      * A TypeScript value on an enum.
      */
    EnumValue = 2,
    /**
      * A TypeScript function.
      */
    Function = 3,
    /**
      * A TypeScript interface.
      */
    Interface = 4,
    /**
      * A TypeScript method.
      */
    Method = 5,
    /**
      * A TypeScript package.
      */
    Package = 6,
    /**
      * A TypeScript parameter.
      */
    Parameter = 7,
    /**
      * A TypeScript property.
      */
    Property = 8,
    /**
      * A TypeScript type literal expression, i.e. which defines an anonymous interface.
      */
    TypeLiteral = 9,
    /**
     * A Typescript class constructor function.
     */
    Constructor = 10,
    /**
     * A Typescript namespace.
     */
    Namespace = 11,
    /**
     * A Typescript BlockScopedVariable.
     */
    ModuleVariable = 12,
}
/**
  * This interface is used to pass options between constructors for AstItem child classes.
  */
export interface IAstItemOptions {
    /**
     * The associated ExtractorContext object for this AstItem
     */
    context: ExtractorContext;
    /**
     * The declaration node for the main syntax item that this AstItem is associated with.
     */
    declaration: ts.Declaration;
    /**
     * The semantic information for the declaration.
     */
    declarationSymbol: ts.Symbol;
    /**
     * The JSDoc-style comment range (including the "/**" characters), which is assumed
     * to be in the same source file as the IAstItemOptions.declaration node.
     * If this is undefined, then the comment will be obtained from the
     * IAstItemOptions.declaration node.
     */
    aedocCommentRange?: ts.TextRange;
    /**
     * The symbol used to export this AstItem from the AstPackage.
     */
    exportSymbol?: ts.Symbol;
}
/**
 * AstItem is an abstract base that represents TypeScript API definitions such as classes,
 * interfaces, enums, properties, functions, and variables.  Rather than directly using the
 * abstract syntax tree from the TypeScript Compiler API, we use AstItem to extract a
 * simplified tree which correponds to the major topics for our API documentation.
 */
export declare abstract class AstItem {
    /**
     * Names of API items should only contain letters, numbers and underscores.
     */
    private static _allowedNameRegex;
    /**
     * The name of the definition, as seen by external consumers of the Public API.
     * For example, suppose a class is defined as "export default class MyClass { }"
     * but exported from the package's index.ts like this:
     *
     *    export { default as _MyClass } from './MyClass';
     *
     * In this example, the AstItem.name would be "_MyClass", i.e. the alias as exported
     * from the top-level AstPackage, not "MyClass" from the original definition.
     */
    name: string;
    /**
     * The name of an API item should be readable and not contain any special characters.
     */
    supportedName: boolean;
    /**
     * Indicates the type of definition represented by this AstItem instance.
     */
    kind: AstItemKind;
    /**
     * A superset of memberItems. Includes memberItems and also other AstItems that
     * comprise this AstItem.
     *
     * Ex: if this AstItem is an AstFunction, then in it's innerItems would
     * consist of AstParameters.
     * Ex: if this AstItem is an AstMember that is a type literal, then it's
     * innerItems would contain ApiProperties.
     */
    innerItems: AstItem[];
    /**
     * True if this AstItem either itself has missing type information or one
     * of it's innerItems is missing type information.
     *
     * Ex: if this AstItem is an AstMethod and has no type on the return value, then
     * we consider the AstItem as 'itself' missing type informations and this property
     * is set to true.
     * Ex: If this AstItem is an AstMethod and one of its innerItems is an AstParameter
     * that has no type specified, then we say an innerItem of this AstMethod is missing
     * type information and this property is set to true.
     */
    hasIncompleteTypes: boolean;
    /**
     * A list of extractor warnings that were reported using AstItem.reportWarning().
     * Whereas an "error" will break the build, a "warning" will merely be tracked in
     * the API file produced by ApiFileGenerator.
     */
    warnings: string[];
    /**
     * The parsed AEDoc comment for this item.
     */
    documentation: ApiDocumentation;
    /**
     * Indicates that this AstItem does not have adequate AEDoc comments. If shouldHaveDocumentation()=true,
     * and there is less than 10 characters of summary text in the AEDoc, then this will be set to true and
     * noted in the API file produced by ApiFileGenerator.
     * (The AEDoc text itself is not included in that report, because documentation
     * changes do not require an API review, and thus should not cause a diff for that report.)
     */
    needsDocumentation: boolean;
    /**
     * The release tag for this item, which may be inherited from a parent.
     * By contrast, ApiDocumentation.releaseTag merely tracks the release tag that was
     * explicitly applied to this item, and does not consider inheritance.
     * @remarks
     * This is calculated during completeInitialization() and should not be used beforehand.
     */
    inheritedReleaseTag: ReleaseTag;
    /**
     * The deprecated message for this item, which may be inherited from a parent.
     * By contrast, ApiDocumentation.deprecatedMessage merely tracks the message that was
     * explicitly applied to this item, and does not consider inheritance.
     * @remarks
     * This is calculated during completeInitialization() and should not be used beforehand.
     */
    inheritedDeprecatedMessage: MarkupElement[];
    /**
     * The ExtractorContext object provides common contextual information for all of
     * items in the AstItem tree.
     */
    protected context: ExtractorContext;
    /**
     * Syntax information from the TypeScript Compiler API, corresponding to the place
     * where this object is originally defined.
     */
    protected declaration: ts.Declaration;
    /**
     * Semantic information from the TypeScript Compiler API, corresponding to the place
     * where this object is originally defined.
     */
    protected declarationSymbol: ts.Symbol;
    /**
     * Semantic information from the TypeScript Compiler API, corresponding to the symbol
     * that is seen by external consumers of the Public API.  For an aliased symbol, this
     * would be the alias that is exported from the top-level package (i.e. AstPackage).
     */
    protected exportSymbol: ts.Symbol;
    protected typeChecker: ts.TypeChecker;
    /**
     * Syntax information from the TypeScript Compiler API, used to locate the file name
     * and line number when reporting an error for this AstItem.
     */
    private _errorNode;
    /**
     * The state of this AstItems references. These references could include \@inheritdoc references
     * or type references.
     */
    private _state;
    private _parentContainer;
    constructor(options: IAstItemOptions);
    /**
     * Called by AstItemContainer.addMemberItem().  Other code should NOT call this method.
     */
    notifyAddedToContainer(parentContainer: AstItemContainer): void;
    /**
     * Called after the constructor to finish the analysis.
     */
    visitTypeReferencesForAstItem(): void;
    /**
     * Return the compiler's underlying Declaration object
     * @todo Generally AstItem classes don't expose ts API objects; we should add
     *       an appropriate member to avoid the need for this.
     */
    getDeclaration(): ts.Declaration;
    /**
     * Return the compiler's underlying Symbol object that contains semantic information about the item
     * @todo Generally AstItem classes don't expose ts API objects; we should add
     *       an appropriate member to avoid the need for this.
     */
    getDeclarationSymbol(): ts.Symbol;
    /**
     * Whether this APiItem should have documentation or not.  If false, then
     * AstItem.missingDocumentation will never be set.
     */
    shouldHaveDocumentation(): boolean;
    /**
     * The AstItemContainer that this member belongs to, or undefined if there is none.
     */
    readonly parentContainer: AstItemContainer | undefined;
    /**
     * This function is a second stage that happens after ExtractorContext.analyze() calls AstItem constructor to build up
     * the abstract syntax tree. In this second stage, we are creating the documentation for each AstItem.
     *
     * This function makes sure we create the documentation for each AstItem in the correct order.
     * In the event that a circular dependency occurs, an error is reported. For example, if AstItemOne has
     * an \@inheritdoc referencing AstItemTwo, and AstItemTwo has an \@inheritdoc referencing AstItemOne then
     * we have a circular dependency and an error will be reported.
     */
    completeInitialization(): void;
    /**
     * A procedure for determining if this AstItem is missing type
     * information. We first check if the AstItem itself is missing
     * any type information and if not then we check each of it's
     * innerItems for missing types.
     *
     * Ex: On the AstItem itself, there may be missing type information
     * on the return value or missing type declaration of itself
     * (const name;).
     * Ex: For each innerItem, there may be an AstParameter that is missing
     * a type. Or for an AstMember that is a type literal, there may be an
     * AstProperty that is missing type information.
     */
    hasAnyIncompleteTypes(): boolean;
    /**
     * Reports an error through the ApiErrorHandler interface that was registered with the Extractor,
     * adding the filename and line number information for the declaration of this AstItem.
     */
    protected reportError(message: string, startIndex?: number): void;
    /**
     * Adds a warning to the AstItem.warnings list.  These warnings will be emitted in the API file
     * produced by ApiFileGenerator.
     */
    protected reportWarning(message: string): void;
    /**
     * This function assumes all references from this AstItem have been resolved and we can now safely create
     * the documentation.
     */
    protected onCompleteInitialization(): void;
    /**
     * This is called by AstItems to visit the types that appear in an expression.  For example,
     * if a Public API function returns a class that is defined in this package, but not exported,
     * this is a problem. visitTypeReferencesForNode() finds all TypeReference child nodes under the
     * specified node and analyzes each one.
     */
    protected visitTypeReferencesForNode(node: ts.Node): void;
    /**
     * This is a helper for visitTypeReferencesForNode().  It analyzes a single TypeReferenceNode.
     */
    private _analyzeTypeReference(typeReferenceNode);
}