ts2md/out/src/JSDocs.d.ts

Simple Typescript Documentation Generator to GitHub Compatible MarkDown

import ts from "typescript";
/**
 * Parsed JSDoc info associated with a documentation item
 *
 * @private
 */
export interface JSDocInfo {
    /**
     * true if has '@private' tag
     */
    isPrivate: boolean;
    /**
     * true if has '@publicbody' tag
     */
    publicBody: boolean;
    /**
     * true if has '@privateinitializer' tag
     */
    privateInitializer: boolean;
    /**
     * JSDoc nodes with ['comment'] strings not otherwise tagged with a recognized tag.
     */
    comments: string[];
    /**
     * The @param tag comments.
     */
    params: ts.JSDocParameterTag[];
    /**
     * JSDoc nodes tagged with '@returns'
     */
    returns: ts.JSDocReturnTag[];
    /**
     * JSDoc nodes tagged with '@throws'
     */
    throws: ts.JSDocThrowsTag[];
    /**
     * The @example tag comments. Comments without code blocks are assumed to be typescript codeblocks
     */
    examples: string[];
    /**
     * The @property tag identifiers and comments. These are forwarded to the relevant member property documentation.
     */
    properties: Record<string, string>;
    /**
     * JSDoc tags not parsed into other properties
     */
    tags: ts.Node[];
    /**
     * JSDoc nodes not parsed into other properties
     */
    other: ts.Node[];
}
/**
 * Parse available JSDoc information on this node.
 *
 * @private
 */
export declare function getJsDocInfo(node: ts.Node, name: string, parent?: DocItem<ts.Node>): JSDocInfo;
/**
 * Wrapper for a Typescript `Node` of a specific derived type,
 * which is of interest for documentation generation.
 *
 * @private
 */
export declare class DocItem<T extends ts.Node> {
    item: T;
    name: string;
    sf: ts.SourceFile;
    parent?: DocItem<ts.Node> | undefined;
    /**
     * Parsed JSDoc information for this item
     */
    jsDoc: JSDocInfo;
    /**
     * Subsidiary documentation nodes when the node has members which
     * are themselves represented as documentation nodes.
     */
    memberDocs: DocBase<ts.Node>[];
    /**
     * This is really here just for demonstration / testing purposes...
     * @param item The typescript Node for this doc item.
     * @param name The name for this doc item.
     * @param sf The source file which defined this item.
     */
    constructor(item: T, name: string, sf: ts.SourceFile, parent?: DocItem<ts.Node> | undefined);
}
/**
 * @private
 */
export interface DocGenSupportApi {
    printer: ts.Printer;
    nothingPrivate: boolean;
    noDetailsSummary: boolean;
    headingLevelMd(relativeLevel: number): string;
}
/**
 * @private
 */
export declare abstract class DocBase<T extends ts.Node> {
    sup: DocGenSupportApi;
    label: string;
    labelPlural: string;
    detailsLabel: string;
    docItems: DocItem<T>[];
    constructor(sup: DocGenSupportApi, label: string, labelPlural: string, detailsLabel?: string);
    abstract getName(item: T, sf: ts.SourceFile): string;
    abstract filterItem(s: ts.Node): T[];
    tryAddItem(s: ts.Node, sf: ts.SourceFile, parent?: DocItem<ts.Node>): void;
    extractMemberDocs(docItem: DocItem<ts.Node>): DocBase<ts.Node>[];
    isNotPrivate(item: ts.Node): boolean;
    findTs(findInTs: string, targetTs: string): {
        pos: number;
        len: number;
    };
    removeTs(fromTs: string, removeTs: string, withSemi?: boolean): string;
    toSeeAlso(docItem: DocItem<T>, mdts: string, mdLinks: Record<string, string>, tight?: boolean): string;
    toTsMarkDown(docItem: DocItem<T>, mdLinks: Record<string, string>, tight?: boolean): string;
    /**
     * Base class implementation of markdown generation for a top level typescript AST node (`DocItem`).
     *
     * Adds relative level 3 heading with `label` and `docItem.name`
     *
     * Adds the nodes simple (no `@` tag) JSDoc nodes under relative level 4 'Description` heading
     *
     * Calls the `toMarkDownTs` override to add the typescript syntax code block for this node.
     *
     * Calls the `toMarkDownDtails` override to add any details markdown for this node.
     *
     * @returns the generated markdown for this `DocItem`
     */
    toMarkDown(docItem: DocItem<T>, mdLinks: Record<string, string>): string;
    /**
     * Generate the typescript syntax for this node to be inserted in a typescript syntax code block
     * in generated markdown.
     *
     * Base class implementation uses the typescript compiler printer on `DocItem` AST node `item`.
     *
     * CAUTION: This adds ALL the source code for this item to the generated markdown. Override SHOULD
     * implement appropriate ommission control policies.
     *
     * @returns typescript syntax to be added within a typescript syntax code block for this `DocItem`
     */
    toMarkDownTs(docItem: DocItem<T>): string;
    /**
     * Generate the 'Details' markdown (including ) for this node.
     *
     * Base class implementation returns an empty string.
     */
    toMarkDownDetails(docItem: DocItem<T>, mdLinks: Record<string, string>): string;
    toMarkDownRefLink(docItem: DocItem<T>): string;
    isExportedDeclaration(item: ts.Declaration): boolean;
    argumentsDetails(docItem: DocItem<T>): string;
    returnsDetails(docItem: DocItem<T>): string;
    throwsDetails(docItem: DocItem<T>): string;
    examplesDetails(docItem: DocItem<T>): string;
    commentsDetails(docItem: DocItem<T>): string;
}
//# sourceMappingURL=JSDocs.d.ts.map