Documenting Storybook with TS and JSDocs

/** 
 * JSDoc 
 */

/**

/** Adds two numbers together */
function add(a, b) {
  return a + b;
}

/**
 * Adds two numbers together
 * @deprecated since version 2.0
 * @param {number} a any number
 * @param {number} b any number
 */
function add(a, b) {
  return a + b;
}

// No errors, including runtime
add("1", 2) // returns "12"

function add(a: number, b: number): number {
  return a + b;
}

interface Props {
  size?: number | string;
}

/**
 * Adds two numbers together
 * @deprecated since version 2.0
 */
function add(a: number, b: number): number {
  return a + b;
}

/** 
 * JSDoc 
 */

export interface ButtonProps {
  /**
   * Is this the principal call to action on the page?
   */
  primary?: Boolean;
  /**
   * What background color to use
   */
  backgroundColor?: string;
  /**
   * How large should the button be?
   */
  size?: "small" | "medium" | "large";
  /**
   * Button contents
   */
  label: string;
  /**
   * Optional click handler
   */
  onClick?: Function;
}

/**
 * Primary UI component for user interaction
 */
export function Button({
  primary = false,
  backgroundColor,
  size = "medium",
  label
}: ButtonProps) {
  /* implementation details here */
}

// Button.stories.tsx
import type { Meta } from "@storybook/react";

import { Button } from "./Button";

const meta: Meta<typeof Button> = {
  component: Button,
  tags: ["autodocs"],
};

export default meta;
type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: {
    primary: true,
    label: "Button",
  },
};

export const Secondary: Story = {
  args: {
    ...Primary.args,
    primary: false,
  },
};

type ColorOption = "brand" | "accent" | "alert" | "none";

export interface ButtonProps {
  /**
   * Is this the principal call to action on the page?
   */
  primary: boolean;
  /**
   * What background color option to use
   */
  backgroundColor?: ColorOption;
  /**
   * How large should the button be?
   */
  size?: "small" | "medium" | "large";
  /**
   * Button contents
   */
  label: string;
  /**
   * Optional click handler
   */
  onClick?: Function;
}

/**
 * Primary UI component for user interaction
 */
export function Button({
  primary = false,
  backgroundColor = 'none',
  size = "medium",
  label
}: ButtonProps) {
  /* implementation details here */
}

// .storybook/main.ts
import type { StorybookConfig } from '@storybook/your-framework';

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['@storybook/addon-essentials'],
  docs: {
    autodocs: 'tag',
    defaultName: 'Documentation',
  },
};

export default config;

{/* DocumentationTemplate.mdx */}

import { Meta, Title, Subtitle, Description, Primary, Controls, Stories } from '@storybook/blocks';

<Meta isTemplate />

<Title />

# Default implementation

<Primary />

## Inputs

The component accepts the following inputs (props):

<Controls />

---

## Additional variations

Listed below are additional variations of the component.

<Stories />

// .storybook/preview.jsx

import DocumentationTemplate from './DocumentationTemplate.mdx';

export default {
  parameters: {
    docs: {
      page: DocumentationTemplate,
    },
  },
};

// .storybook/blocks/StoryName.jsx

import { useOf } from '@storybook/blocks';

export const StoryName = ({ of }) => {
  const resolvedOf = useOf(of || 'story', ['story', 'meta']);
  switch (resolvedOf.type) {
    case 'story': {
      return <h1>{resolvedOf.story.name}</h1>;
    }
    case 'meta': {
      return <h1>{resolvedOf.preparedMeta.title}</h1>;
    }
  }
  return null;
};

{/* ButtonDocs.mdx */}

import { Meta } from '@storybook/blocks';
import { StoryName } from '../.storybook/blocks/StoryName';
import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

{/* renders "Secondary" */}
<StoryName of={ButtonStories.Secondary} />

{/* renders "Primary" */}
<StoryName />

{/* renders "Button" */}
<StoryName of={ButtonStories} />