@microsoft/api-extractor/lib/markup/Markup.d.ts

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

import { MarkupElement, MarkupBasicElement, IMarkupWebLink, IMarkupApiLink, IMarkupText, IMarkupParagraph, IMarkupLineBreak, IMarkupTable, IMarkupTableRow, IMarkupHeading1, IMarkupHeading2, IMarkupPage, IMarkupHighlightedText, MarkupLinkTextElement, IMarkupNoteBox, IMarkupCodeBox, MarkupHighlighter } from './MarkupElement';
import { IApiItemReference } from '../api/ApiItem';
/**
 * Options for {@link Markup.createTextElements}
 *
 * @public
 */
export interface IMarkupCreateTextOptions {
    /**
     * Whether the text should be boldfaced.
     */
    bold?: boolean;
    /**
     * Whether the text should be italicized.
     */
    italics?: boolean;
}
/**
 * Provides various operations for working with MarkupElement objects.
 *
 * @public
 */
export declare class Markup {
    /**
     * A predefined constant for the IMarkupLineBreak element.
     */
    static BREAK: IMarkupLineBreak;
    /**
     * A predefined constant for the IMarkupParagraph element.
     */
    static PARAGRAPH: IMarkupParagraph;
    /**
     * Constructs an IMarkupText element representing the specified text string, with
     * optional formatting.
     *
     * @remarks
     * NOTE: All whitespace (including newlines) will be collapsed to single spaces.
     * This behavior is similar to how HTML handles whitespace.  To preserve
     * newlines, use {@link Markup.createTextParagraphs} instead.
     */
    static createTextElements(text: string, options?: IMarkupCreateTextOptions): IMarkupText[];
    /**
     * This function is similar to {@link Markup.createTextElements}, except that multiple newlines
     * will be converted to a Markup.PARAGRAPH object.
     */
    static createTextParagraphs(text: string, options?: IMarkupCreateTextOptions): MarkupBasicElement[];
    /**
     * Constructs an IMarkupApiLink element that represents a hyperlink to the specified
     * API object.  The hyperlink is applied to an existing stream of markup elements.
     * @param textElements - the markup sequence that will serve as the link text
     * @param target - the API object that the hyperlink will point to
     */
    static createApiLink(textElements: MarkupLinkTextElement[], target: IApiItemReference): IMarkupApiLink;
    /**
     * Constructs an IMarkupApiLink element that represents a hyperlink to the specified
     * API object.  The hyperlink is applied to a plain text string.
     * @param text - the text string that will serve as the link text
     * @param target - the API object that the hyperlink will point to
     */
    static createApiLinkFromText(text: string, target: IApiItemReference): IMarkupApiLink;
    /**
     * Constructs an IMarkupWebLink element that represents a hyperlink an internet URL.
     * @param textElements - the markup sequence that will serve as the link text
     * @param targetUrl - the URL that the hyperlink will point to
     */
    static createWebLink(textElements: MarkupLinkTextElement[], targetUrl: string): IMarkupWebLink;
    /**
     * Constructs an IMarkupWebLink element that represents a hyperlink an internet URL.
     * @param text - the plain text string that will serve as the link text
     * @param targetUrl - the URL that the hyperlink will point to
     */
    static createWebLinkFromText(text: string, targetUrl: string): IMarkupWebLink;
    /**
     * Constructs an IMarkupHighlightedText element representing a program code text
     * with optional syntax highlighting
     */
    static createCode(code: string, highlighter?: MarkupHighlighter): IMarkupHighlightedText;
    /**
     * Constructs an IMarkupHeading1 element with the specified title text
     */
    static createHeading1(text: string): IMarkupHeading1;
    /**
     * Constructs an IMarkupHeading2 element with the specified title text
     */
    static createHeading2(text: string): IMarkupHeading2;
    /**
     * Constructs an IMarkupCodeBox element representing a program code text
     * with the specified syntax highlighting
     */
    static createCodeBox(code: string, highlighter: MarkupHighlighter): IMarkupCodeBox;
    /**
     * Constructs an IMarkupNoteBox element that will display the specified markup content
     */
    static createNoteBox(textElements: MarkupBasicElement[]): IMarkupNoteBox;
    /**
     * Constructs an IMarkupNoteBox element that will display the specified plain text string
     */
    static createNoteBoxFromText(text: string): IMarkupNoteBox;
    /**
     * Constructs an IMarkupTableRow element containing the specified cells, which each contain a
     * sequence of MarkupBasicElement content
     */
    static createTableRow(cellValues?: MarkupBasicElement[][] | undefined): IMarkupTableRow;
    /**
     * Constructs an IMarkupTable element containing the specified header cells, which each contain a
     * sequence of MarkupBasicElement content.
     * @remarks
     * The table initially has zero rows.
     */
    static createTable(headerCellValues?: MarkupBasicElement[][] | undefined): IMarkupTable;
    /**
     * Constructs an IMarkupTable element with the specified title.
     */
    static createPage(title: string): IMarkupPage;
    /**
     * Extracts plain text from the provided markup elements, discarding any formatting.
     *
     * @remarks
     * The returned string is suitable for counting words or extracting search keywords.
     * Its formatting is not guaranteed, and may change in future updates of this API.
     *
     * API Extractor determines whether an API is "undocumented" by using extractTextContent()
     * to extract the text from its summary, and then counting the number of words.
     */
    static extractTextContent(elements: MarkupElement[]): string;
    /**
     * Use this to clean up a MarkupElement sequence, assuming the sequence is now in
     * its final form.
     *
     * @remarks
     * The following operations are performed:
     *
     * 1. Remove leading/trailing white space around paragraphs
     *
     * 2. Remove redundant paragraph elements
     */
    static normalize<T extends MarkupElement>(elements: T[]): void;
    private static _extractTextContent(elements, buffer);
    private static _trimRawText(text);
}