Home > @microsoft/api-extractor-model > Excerpt

Excerpt class

The Excerpt class is used by ApiDeclaredItem to represent a TypeScript code fragment that may be annotated with hyperlinks to declared types (and in the future, source code locations).


export declare class Excerpt 


API Extractor’s .api.json file format stores excerpts compactly as a start/end indexes into an array of tokens. Every ApiDeclaredItem has a “main excerpt” corresponding to the full list of tokens. The declaration may also have have “captured” excerpts that correspond to subranges of tokens.

For example, if the main excerpt is:

function parse(s: string): Vector | undefined;

…then this entire signature is the “main excerpt”, whereas the function’s return type Vector | undefined is a captured excerpt. The Vector token might be a hyperlink to that API item.

An excerpt may be empty (i.e. a token range containing zero tokens). For example, if a function’s return value is not explicitly declared, then the returnTypeExcerpt will be empty. By contrast, a class constructor cannot have a return value, so ApiConstructor has no returnTypeExcerpt property at all.


Constructor Modifiers Description
(constructor)(tokens, tokenRange)   Constructs a new instance of the Excerpt class


Property Modifiers Type Description
isEmpty   boolean Returns true if the excerpt is an empty range.
spannedTokens   ReadonlyArray<ExcerptToken> The tokens spanned by this excerpt. It is the range of the tokens array as specified by the tokenRange property.
text   string The excerpted text, formed by concatenating the text of the spannedTokens strings.
tokenRange   Readonly<IExcerptTokenRange> Specifies the excerpt’s range within the tokens array.
tokens   ReadonlyArray<ExcerptToken> The complete list of tokens for the source code fragment that this excerpt is based upon. If this object is the main excerpt, then it will span all of the tokens; otherwise, it will correspond to a range within the array.