Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(lint): enforce @example code fence format in docblocks (#485)

Cindy Zhangb19d07c6aee2
diff --git a/internal/eslint-plugin-xds/docblock-example-format.js b/internal/eslint-plugin-xds/docblock-example-format.js
new file mode 100644
index 0000000000..09800f4bfd
--- /dev/null
+++ b/internal/eslint-plugin-xds/docblock-example-format.js
@@ -0,0 +1,92 @@
+/**
+ * @file docblock-example-format.js
+ * @description ESLint rule enforcing @example blocks use fenced code.
+ *
+ * Valid:
+ * @example
+ * ```
+ * <XDSButton label="Click" />
+ * ```
+ *
+ * Invalid:
+ * @example <XDSButton label="Click" />
+ * @example
+ * <XDSButton label="Click" />
+ */
+
+/**
+ * Checks JSDoc comments for @example formatting violations.
+ *
+ * Pattern 1 (inline): @example followed by code on the same line
+ * e.g. `@example getInitials('John') // 'J'`
+ *
+ * Pattern 2 (missing fence): @example on its own line, but the next
+ * non-empty line is not a code fence (```)
+ */
+const docblockExampleFormatRule = {
+ meta: {
+ type: 'suggestion',
+ docs: {
+ description:
+ 'Enforce @example blocks use ``` fenced code on a separate line',
+ category: 'Stylistic Issues',
+ recommended: true,
+ },
+ fixable: 'code',
+ messages: {
+ inlineExample:
+ '@example must not have code on the same line. Put ``` on the next line, then the code.',
+ missingFence:
+ '@example must be followed by a ``` code fence on the next line.',
+ },
+ schema: [],
+ },
+ create(context) {
+ const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+ return {
+ Program() {
+ const comments = sourceCode.getAllComments();
+
+ for (const comment of comments) {
+ if (comment.type !== 'Block') continue;
+
+ const lines = comment.value.split('\n');
+
+ for (let i = 0; i < lines.length; i++) {
+ const line = lines[i];
+ const trimmed = line.replace(/^\s*\*?\s*/, '');
+
+ // Pattern 1: @example with code on the same line
+ // e.g. "@example getInitials('John')" or '@example "mod+k"'
+ if (/^@example\s+\S/.test(trimmed)) {
+ context.report({
+ node: comment,
+ messageId: 'inlineExample',
+ });
+ continue;
+ }
+
+ // Pattern 2: @example alone, but next non-empty line isn't ```
+ if (/^@example\s*$/.test(trimmed)) {
+ // Look ahead for the next non-empty comment line
+ for (let j = i + 1; j < lines.length; j++) {
+ const nextTrimmed = lines[j].replace(/^\s*\*?\s*/, '');
+ if (nextTrimmed === '') continue; // skip blank lines
+ if (!nextTrimmed.startsWith('```')) {
+ context.report({
+ node: comment,
+ messageId: 'missingFence',
+ });
+ }
+ break; // only check the first non-empty line after @example
+ }
+ }
+ }
+ }
+ },
+ };
+ },
+};
+
+export default docblockExampleFormatRule;
diff --git a/internal/eslint-plugin-xds/docblock-example-format.test.mjs b/internal/eslint-plugin-xds/docblock-example-format.test.mjs
new file mode 100644
index 0000000000..f64fa49f84
--- /dev/null
+++ b/internal/eslint-plugin-xds/docblock-example-format.test.mjs
@@ -0,0 +1,173 @@
+/**
+ * @file docblock-example-format.test.mjs
+ * Tests for the docblock-example-format ESLint rule.
+ */
+
+import {describe, it} from 'vitest';
+import {RuleTester} from 'eslint';
+import tseslint from 'typescript-eslint';
+import docblockExampleFormatRule from './docblock-example-format.js';
+
+const ruleTester = new RuleTester({
+ languageOptions: {
+ parser: tseslint.parser,
+ parserOptions: {
+ ecmaFeatures: {jsx: true},
+ },
+ },
+});
+
+describe('docblock-example-format', () => {
+ruleTester.run('docblock-example-format', docblockExampleFormatRule, {
+ valid: [
+ // Pattern 1: @example on its own line, ``` on next line
+ {
+ code: `
+/**
+ * A button component.
+ *
+ * @example
+ * \`\`\`
+ * <Button label="Click" />
+ * \`\`\`
+ */
+function Button() {}
+ `,
+ },
+ // @example with ```tsx language tag
+ {
+ code: `
+/**
+ * @example
+ * \`\`\`tsx
+ * <Button label="Click" />
+ * \`\`\`
+ */
+function Button() {}
+ `,
+ },
+ // No @example at all — perfectly fine
+ {
+ code: `
+/**
+ * A simple helper function.
+ */
+function helper() {}
+ `,
+ },
+ // @example with blank line before fence — still valid
+ {
+ code: `
+/**
+ * @example
+ *
+ * \`\`\`
+ * <Button />
+ * \`\`\`
+ */
+function Button() {}
+ `,
+ },
+ // Multiple valid @example blocks
+ {
+ code: `
+/**
+ * @example
+ * \`\`\`
+ * <Button variant="primary" />
+ * \`\`\`
+ *
+ * @example
+ * \`\`\`
+ * <Button variant="ghost" />
+ * \`\`\`
+ */
+function Button() {}
+ `,
+ },
+ ],
+
+ invalid: [
+ // Inline: @example with code on the same line
+ {
+ code: `
+/**
+ * @example getInitials('John Doe') // 'JD'
+ */
+function getInitials() {}
+ `,
+ errors: [{messageId: 'inlineExample'}],
+ },
+ // Inline: @example with JSX on same line
+ {
+ code: `
+/**
+ * @example <Button label="Click" />
+ */
+function Button() {}
+ `,
+ errors: [{messageId: 'inlineExample'}],
+ },
+ // Inline: @example with string on same line
+ {
+ code: `
+/**
+ * @example "mod+k", "mod+shift+p"
+ */
+function Shortcut() {}
+ `,
+ errors: [{messageId: 'inlineExample'}],
+ },
+ // Missing fence: @example then code without ```
+ {
+ code: `
+/**
+ * @example
+ * <Button label="Click" />
+ */
+function Button() {}
+ `,
+ errors: [{messageId: 'missingFence'}],
+ },
+ // Missing fence: @example then comment without ```
+ {
+ code: `
+/**
+ * @example
+ * // Default usage
+ * <Button label="Click" />
+ */
+function Button() {}
+ `,
+ errors: [{messageId: 'missingFence'}],
+ },
+ // Mixed: one valid, one inline
+ {
+ code: `
+/**
+ * @example
+ * \`\`\`
+ * <Button />
+ * \`\`\`
+ *
+ * @example dividers={['top']}
+ */
+function Section() {}
+ `,
+ errors: [{messageId: 'inlineExample'}],
+ },
+ // Prop-level docblock with inline example
+ {
+ code: `
+interface Props {
+ /**
+ * @example dividers={['top', 'bottom']}
+ */
+ dividers?: string[];
+}
+ `,
+ errors: [{messageId: 'inlineExample'}],
+ },
+ ],
+});
+});
diff --git a/internal/eslint-plugin-xds/index.js b/internal/eslint-plugin-xds/index.js
index 9ccdead8bc..ed9c3efc1f 100644
--- a/internal/eslint-plugin-xds/index.js
+++ b/internal/eslint-plugin-xds/index.js
@@ -5,6 +5,7 @@
* Rules:
* - no-hardcoded-styles: Enforces usage of design tokens instead of hardcoded values in StyleX
* - boolean-prop-naming: Enforces is/has prefix on boolean props in *Props interfaces
+ * - docblock-example-format: Enforces @example blocks use ``` fenced code on a separate line
*
* Philosophy: Strict for agents (CI), lenient for humans (local dev)
* - "strict" config: All rules as errors - use in CI/agent environments
@@ -12,6 +13,7 @@
*/
import booleanPropNamingRule from './boolean-prop-naming.js';
+import docblockExampleFormatRule from './docblock-example-format.js';
// =============================================================================
// Rule: no-hardcoded-styles
@@ -213,6 +215,7 @@ const plugin = {
rules: {
'no-hardcoded-styles': noHardcodedStylesRule,
'boolean-prop-naming': booleanPropNamingRule,
+ 'docblock-example-format': docblockExampleFormatRule,
},
configs: {},
};
@@ -225,6 +228,7 @@ plugin.configs.strict = {
rules: {
'@xds/no-hardcoded-styles': 'error',
'@xds/boolean-prop-naming': 'error',
+ '@xds/docblock-example-format': 'error',
},
};
@@ -236,6 +240,7 @@ plugin.configs.recommended = {
rules: {
'@xds/no-hardcoded-styles': 'warn',
'@xds/boolean-prop-naming': 'warn',
+ '@xds/docblock-example-format': 'warn',
},
};
diff --git a/packages/core/src/Avatar/XDSAvatar.tsx b/packages/core/src/Avatar/XDSAvatar.tsx
index 34f67b2099..09dd046df6 100644
--- a/packages/core/src/Avatar/XDSAvatar.tsx
+++ b/packages/core/src/Avatar/XDSAvatar.tsx
@@ -220,8 +220,11 @@ export interface XDSAvatarProps extends Omit<
/**
* Generates initials from a name string.
* Takes the first letter of the first two words.
- * @example getInitials('John Doe') // 'JD'
- * @example getInitials('Alice') // 'A'
+ * @example
+ * ```
+ * getInitials('John Doe') // 'JD'
+ * getInitials('Alice') // 'A'
+ * ```
*/
function getInitials(name: string): string {
const words = name.trim().split(/\s+/);
diff --git a/packages/core/src/Banner/XDSBanner.tsx b/packages/core/src/Banner/XDSBanner.tsx
index 5d6418d249..ffcc79ad4d 100644
--- a/packages/core/src/Banner/XDSBanner.tsx
+++ b/packages/core/src/Banner/XDSBanner.tsx
@@ -92,7 +92,9 @@ export interface XDSBannerProps {
* Typically an XDSButton with a secondary or ghost variant.
*
* @example
+ * ```
* endContent={<XDSButton label="Retry" variant="ghost" onClick={handleRetry} />}
+ * ```
*/
endContent?: ReactNode;
/**
diff --git a/packages/core/src/Calendar/XDSCalendar.tsx b/packages/core/src/Calendar/XDSCalendar.tsx
index 81136bc934..1c5fce5ee8 100644
--- a/packages/core/src/Calendar/XDSCalendar.tsx
+++ b/packages/core/src/Calendar/XDSCalendar.tsx
@@ -183,7 +183,9 @@ export type XDSCalendarProps = XDSCalendarSingleProps | XDSCalendarRangeProps;
* A calendar component for selecting dates or date ranges.
*
* @example
+ * ```
* <XDSCalendar value={selectedDate} onChange={setSelectedDate} />
+ * ```
*/
export const XDSCalendar = forwardRef<XDSCalendarHandle, XDSCalendarProps>(
(props, ref) => {
diff --git a/packages/core/src/CommandPalette/XDSCommandPaletteShortcut.tsx b/packages/core/src/CommandPalette/XDSCommandPaletteShortcut.tsx
index 30cd9ad20f..a11e231192 100644
--- a/packages/core/src/CommandPalette/XDSCommandPaletteShortcut.tsx
+++ b/packages/core/src/CommandPalette/XDSCommandPaletteShortcut.tsx
@@ -46,14 +46,14 @@ const styles = stylex.create({
* Map of modifier key names to display symbols.
*/
const KEY_DISPLAY: Record<string, string> = {
- mod: '\u2318', // ⌘
- ctrl: '\u2303', // ⌃
- alt: '\u2325', // ⌥
- shift: '\u21E7', // ⇧
- enter: '\u21B5', // ↵
+ mod: '\u2318', // ⌘
+ ctrl: '\u2303', // ⌃
+ alt: '\u2325', // ⌥
+ shift: '\u21E7', // ⇧
+ enter: '\u21B5', // ↵
backspace: '\u232B', // ⌫
escape: 'Esc',
- tab: '\u21E5', // ⇥
+ tab: '\u21E5', // ⇥
up: '\u2191',
down: '\u2193',
left: '\u2190',
@@ -65,7 +65,10 @@ export interface XDSCommandPaletteShortcutProps {
* Keyboard shortcut string. Use "+" to separate keys.
* Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape.
*
- * @example "mod+k", "mod+shift+p", "enter"
+ * @example
+ * ```
+ * "mod+k", "mod+shift+p", "enter"
+ * ```
*/
keys: string;
}
@@ -82,7 +85,7 @@ export interface XDSCommandPaletteShortcutProps {
export function XDSCommandPaletteShortcut({
keys,
}: XDSCommandPaletteShortcutProps) {
- const parts = keys.split('+').map((key) => key.trim().toLowerCase());
+ const parts = keys.split('+').map(key => key.trim().toLowerCase());
return (
<span {...stylex.props(styles.wrapper)} aria-hidden="true">
diff --git a/packages/core/src/Pagination/XDSPagination.tsx b/packages/core/src/Pagination/XDSPagination.tsx
index 5eff85da39..05f06b67d5 100644
--- a/packages/core/src/Pagination/XDSPagination.tsx
+++ b/packages/core/src/Pagination/XDSPagination.tsx
@@ -233,9 +233,11 @@ const styles = stylex.create({
* Returns an array of page numbers and '...' strings.
*
* @example
+ * ```
* generatePageRange(5, 10, 1) → [1, '...', 4, 5, 6, '...', 10]
* generatePageRange(1, 10, 1) → [1, 2, 3, '...', 10]
* generatePageRange(1, 5, 1) → [1, 2, 3, 4, 5]
+ * ```
*/
export function generatePageRange(
currentPage: number,
diff --git a/packages/core/src/Section/XDSSection.tsx b/packages/core/src/Section/XDSSection.tsx
index 20daf48cac..dc8cfec101 100644
--- a/packages/core/src/Section/XDSSection.tsx
+++ b/packages/core/src/Section/XDSSection.tsx
@@ -167,7 +167,10 @@ export interface XDSSectionProps {
/**
* Which sides should have divider borders.
* Use 'start'/'end' for horizontal (respects RTL).
- * @example dividers={['top', 'bottom']}
+ * @example
+ * ```
+ * dividers={['top', 'bottom']}
+ * ```
*/
dividers?: Array<'top' | 'bottom' | 'start' | 'end'>;
diff --git a/packages/core/src/Table/columnUtils.ts b/packages/core/src/Table/columnUtils.ts
index 8e7abbb4c5..bbc9845f0d 100644
--- a/packages/core/src/Table/columnUtils.ts
+++ b/packages/core/src/Table/columnUtils.ts
@@ -21,7 +21,10 @@ import type {
* Create a proportional column width (fr-like).
* Columns share available space proportionally.
*
- * @example proportional(2) // twice as wide as proportional(1)
+ * @example
+ * ```
+ * proportional(2) // twice as wide as proportional(1)
+ * ```
*/
export function proportional(value: number = 1): ProportionalWidth {
return {type: 'proportional', value};
@@ -30,7 +33,10 @@ export function proportional(value: number = 1): ProportionalWidth {
/**
* Create a fixed pixel column width.
*
- * @example pixel(200) // exactly 200px wide
+ * @example
+ * ```
+ * pixel(200) // exactly 200px wide
+ * ```
*/
export function pixel(value: number): PixelWidth {
return {type: 'pixel', value};
diff --git a/packages/core/src/Text/XDSFontWrapper.tsx b/packages/core/src/Text/XDSFontWrapper.tsx
index 6890b622f2..d4cf469af7 100644
--- a/packages/core/src/Text/XDSFontWrapper.tsx
+++ b/packages/core/src/Text/XDSFontWrapper.tsx
@@ -49,6 +49,7 @@ export interface XDSFontWrapperProps {
* Uses the reset.css stylesheet which references theme CSS custom properties.
*
* @example
+ * ```
* // Default variant (dense scale)
* <XDSFontWrapper>
* <h1>Page Title</h1>
@@ -59,17 +60,16 @@ export interface XDSFontWrapperProps {
* </ul>
* </XDSFontWrapper>
*
- * @example
* // Editorial variant (larger heading scale)
* <XDSFontWrapper variant="editorial">
* <h1>Article Title</h1>
* <p>Body text for long-form content.</p>
* </XDSFontWrapper>
*
- * @example
* // For global usage, apply to body:
* // import '@xds/core/typography.css';
* // <body className="xds-typography">
+ * ```
*/
export function XDSFontWrapper({
variant = 'default',
@@ -104,10 +104,12 @@ XDSFontWrapper.displayName = 'XDSFontWrapper';
* Use this for applying styles to native HTML elements programmatically.
*
* @example
+ * ```
* const { headingStyles, proseStyles } = useXDSFontWrapperStyles();
*
* <h1 {...stylex.props(headingStyles?.h1)}>Title</h1>
* <p {...stylex.props(proseStyles?.p)}>Paragraph</p>
+ * ```
*/
export function useXDSFontWrapperStyles() {
const themeContext = useTheme();
diff --git a/packages/core/src/Text/XDSHeading.tsx b/packages/core/src/Text/XDSHeading.tsx
index 2736389f0a..431f53fc95 100644
--- a/packages/core/src/Text/XDSHeading.tsx
+++ b/packages/core/src/Text/XDSHeading.tsx
@@ -74,8 +74,10 @@ export interface XDSHeadingProps {
* @default Same as `level`
*
* @example
+ * ```
* // Visually styled as h2, but semantically h3 in document outline
* <XDSHeading level={2} accessibilityLevel={3}>Sidebar Section</XDSHeading>
+ * ```
*/
accessibilityLevel?: XDSHeadingLevel;
diff --git a/packages/core/src/utils/dateParser.ts b/packages/core/src/utils/dateParser.ts
index 442e932761..b8dfd371b3 100644
--- a/packages/core/src/utils/dateParser.ts
+++ b/packages/core/src/utils/dateParser.ts
@@ -243,7 +243,9 @@ export function parseISO(iso: ISODateString): Date {
* Uses locale-aware formatting with full month name.
*
* @example
+ * ```
* formatDisplayDate("2026-01-25") // "January 25, 2026"
+ * ```
*/
export function formatDisplayDate(iso: ISODateString): string {
const date = parseISO(iso);