@mui/internal-docs-infra
Version:
MUI Infra - internal documentation creation tools.
53 lines • 2.21 kB
text/typescript
/**
* Extracts JSDoc comments from highlighted type declaration HAST trees.
*
* Operates on a `pre > code > span.frame > span.line*` HAST structure produced
* by `formatDetailedTypeAsHast`. Walks the HAST span elements (pl-v, pl-k, pl-en,
* pl-s, pl-c, etc.) to structurally identify property declarations, extract their
* types, and associate pending JSDoc comments.
*
* Splits the single frame into multiple alternating frames at the `code.children`
* level — comment frames carry `data-comment` for CSS hiding, non-comment frames
* are normal.
*
* Supports deep extraction for nested object types using dot-notation
* property paths (e.g., `appearance.theme`).
*/
import type { HastRoot } from "../../CodeHighlighter/types.mjs";
/**
* Information extracted from a property declaration, optionally with JSDoc.
*/
export interface ExtractedTypeComment {
/** The JSDoc description text, if a comment is present */
description?: string;
/** The property's type string as it appears in the declaration */
typeText: string;
/** Whether the property is optional (has `?:`) */
optional: boolean;
/** JSDoc `@default` value, if present */
defaultValue?: string;
/** JSDoc `@deprecated` text, if present */
deprecated?: string;
/** JSDoc `@see` references, if present */
see?: string[];
/** JSDoc `@example` text, if present */
example?: string;
}
/**
* Result of extracting type comments from a highlighted HAST.
*/
export interface ExtractTypePropsResult {
/** The HAST with JSDoc comment lines wrapped in `span[data-comment]` elements */
hast: HastRoot;
/** Map of dot-notation property paths to their extracted comment data */
properties: Record<string, ExtractedTypeComment>;
}
/**
* Extracts JSDoc comments from a highlighted type declaration HAST and returns
* a restructured HAST (single frame split into alternating comment/non-comment frames
* via `restructureFrames`) plus a map of property paths to extracted data.
*
* Property paths use dot-notation for nested object types, such as
* "appearance.theme" for a property "theme" nested inside "appearance".
*/
export declare function extractTypeProps(hast: HastRoot): ExtractTypePropsResult;