Rush StackShopBlogEvents
Skip to main content

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)(tokens, tokenRange)Constructs a new instance of the Excerpt class


isEmptyreadonlybooleanReturns true if the excerpt is an empty range.
spannedTokensreadonlyReadonlyArray<ExcerptToken>The tokens spanned by this excerpt. It is the range of the tokens array as specified by the tokenRange property.
textreadonlystringThe excerpted text, formed by concatenating the text of the spannedTokens strings.
tokenRangereadonlyReadonly<IExcerptTokenRange>Specifies the excerpt's range within the tokens array.
tokensreadonlyReadonlyArray<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.