@microsoft/api-extractor/lib/aedoc/ApiDocumentation.d.ts

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

import { TextRange } from '@microsoft/tsdoc';
import { AstPackage } from '../ast/AstPackage';
import { ApiDefinitionReference } from '../ApiDefinitionReference';
import { ExtractorContext } from '../ExtractorContext';
import { ResolvedApiItem } from '../ResolvedApiItem';
import { ReleaseTag } from './ReleaseTag';
import { MarkupElement, MarkupBasicElement, IMarkupApiLink } from '../markup/MarkupElement';
/**
 * A dependency for ApiDocumentation constructor that abstracts away the function
 * of resolving an API definition reference.
 *
 * @internalremarks reportError() will be called if the apiDefinitionRef is to a non local
 * item and the package of that non local item can not be found.
 * If there is no package given and an  item can not be found we will return undefined.
 * Once we support local references, we can be sure that reportError will only be
 * called once if the item can not be found (and undefined will be returned by the reference
 * function).
 */
export interface IReferenceResolver {
    resolve(apiDefinitionRef: ApiDefinitionReference, astPackage: AstPackage, warnings: string[]): ResolvedApiItem | undefined;
}
/**
 * Used by ApiDocumentation to represent the AEDoc description for a function parameter.
 */
export interface IAedocParameter {
    name: string;
    description: MarkupBasicElement[];
}
export declare class ApiDocumentation {
    /**
     * docCommentTokens that are parsed into Doc Elements.
     */
    summary: MarkupElement[];
    deprecatedMessage: MarkupBasicElement[];
    remarks: MarkupElement[];
    returnsMessage: MarkupBasicElement[];
    parameters: {
        [name: string]: IAedocParameter;
    };
    /**
     * A list of \@link elements to be post-processed after all basic documentation has been created
     * for all items in the project.  We save the processing for later because we need ReleaseTag
     * information before we can determine whether a link element is valid.
     * Example: If API item A has a \@link in its documentation to API item B, then B must not
     * have ReleaseTag.Internal.
     */
    incompleteLinks: IMarkupApiLink[];
    /**
     * A "release tag" is an AEDoc tag which indicates whether this definition
     * is considered Public API for third party developers, as well as its release
     * stage (alpha, beta, etc).
     */
    releaseTag: ReleaseTag;
    /**
     * True if the "\@preapproved" tag was specified.
     * Indicates that this internal API is exempt from further reviews.
     */
    preapproved: boolean | undefined;
    /**
     * True if the "\@packagedocumentation" tag was specified.
     */
    isPackageDocumentation: boolean | undefined;
    /**
     * True if the documentation content has not been reviewed yet.
     */
    isDocBeta: boolean | undefined;
    /**
     * True if the \@eventproperty tag was specified.  This means class/interface property
     * represents and event.  It should be a read-only property that returns a user-defined class
     * with operations such as addEventHandler() or removeEventHandler().
     */
    isEventProperty: boolean | undefined;
    /**
     * True if the \@inheritdoc tag was specified.
     */
    isDocInherited: boolean | undefined;
    /**
     * True if the \@inheritdoc tag was specified and is inheriting from a target object
     * that was marked as \@deprecated.
     */
    isDocInheritedDeprecated: boolean | undefined;
    /**
     * True if the \@readonly tag was specified.
     */
    hasReadOnlyTag: boolean | undefined;
    warnings: string[];
    /**
     * Whether the "\@sealed" AEDoc tag was specified.
     */
    isSealed: boolean;
    /**
     * Whether the "\@virtual" AEDoc tag was specified.
     */
    isVirtual: boolean;
    /**
     * Whether the "\@override" AEDoc tag was specified.
     */
    isOverride: boolean;
    /**
     * A function type interface that abstracts away resolving
     * an API definition reference to an item that has friendly
     * accessible AstItem properties.
     *
     * Ex: this is useful in the case of parsing inheritdoc expressions,
     * in the sense that we do not know if we the inherited documentation
     * is coming from an AstItem or a ApiItem.
     */
    referenceResolver: IReferenceResolver;
    /**
     * We need the extractor to access the package that this AstItem
     * belongs to in order to resolve references.
     */
    context: ExtractorContext;
    /**
     * True if any errors were encountered while parsing the AEDoc tokens.
     * This is used to suppress other "collateral damage" errors, e.g. if "@public" was
     * misspelled then we shouldn't also complain that the "@public" tag is missing.
     */
    failedToParse: boolean;
    readonly reportError: (message: string, startIndex?: number) => void;
    private _parserContext;
    private _docComment;
    constructor(inputTextRange: TextRange, referenceResolver: IReferenceResolver, context: ExtractorContext, errorLogger: (message: string, startIndex?: number) => void, warnings: string[]);
    /**
     * Returns true if an AEDoc comment was parsed for the API item.
     */
    readonly aedocCommentFound: boolean;
    /**
     * Returns the original AEDoc comment
     */
    emitNormalizedComment(): string;
    /**
     * Executes the implementation details involved in completing the documentation initialization.
     * Currently completes link and inheritdocs.
     */
    completeInitialization(warnings: string[]): void;
    private _parseDocs(inputTextRange);
    private _parseModifierTags();
    private _parseReleaseTag(modifierTagSet, tagDefinition, releaseTag);
    private _parseSections();
    private _renderAsMarkupElementsInto(result, node, sectionName, allowStructuredContent);
    private _reportIncorrectStructuredContent(constructName, sectionName);
    private _tryCreateApiItemReference(declarationReference);
    private _tryGetMemberReferenceIdentifier(memberReference);
    /**
     * A processing of linkDocElements that refer to an ApiDefinitionReference. This method
     * ensures that the reference is to an API item that is not 'Internal'.
     */
    private _completeLinks();
    /**
     * A processing of inheritdoc 'Tokens'. This processing occurs after we have created documentation
     * for all API items.
     */
    private _completeInheritdocs(warnings);
}