[Bug]: JSDocs appearing inside docs page

ipetinate commented 3 weeks ago

Describe the bug

Storybook is placing the JSDocs annotations of my components on the page generated by autodocs.

And in some components, it caused the correct functioning to break.

https://github.com/user-attachments/assets/1e9028f1-53cd-4aaa-b891-40b0dd2e048f

Code examples

Component

import { useTheme } from "@/hooks/useTheme";
import { MoonIcon, SunIcon } from "@heroicons/react/24/outline";
import { Switch } from "@nextui-org/react";
import { useTranslation } from "react-i18next";

type ThemeSwitchProps = {
noLabel?: boolean;
};

/**
* Renders a theme switch component.
*
* @param {Object} props - The component props.
* @param {boolean} props.noLabel - Determines whether to display the label or not.
* @returns {JSX.Element} The rendered theme switch component.
*
* @example
* // Default
* <ThemeSwitch />
*
* // No Label (only switch)
* <ThemeSwitch noLabel />
*/
export function ThemeSwitch({ noLabel }: ThemeSwitchProps): JSX.Element {
const { t } = useTranslation();
const { theme, toggleTheme } = useTheme();

return (
  <Switch
    size="md"
    color="secondary"
    isSelected={theme === "light"}
    aria-label="Theme switcher"
    onValueChange={() => toggleTheme()}
    thumbIcon={({ isSelected, className }) =>
      isSelected ? (
        <SunIcon className={className} />
      ) : (
        <MoonIcon className={className} />
      )
    }
  >
    {!noLabel
      ? theme === "dark"
        ? t("theme.label.dark")
        : t("theme.label.light")
      : undefined}
  </Switch>
);
}

Story

import type { Meta, StoryObj } from "@storybook/react";

import { ThemeSwitch } from "./ThemeSwitch";

const meta: Meta<typeof ThemeSwitch> = {
component: ThemeSwitch,
};

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

export const Primary: Story = {
args: {},
};

export const OnlySwitch: Story = {
args: {
  noLabel: true,
},
};

Deps and Dev Deps

{
  "dependencies": {
    "@heroicons/react": "^2.1.5",
    "@nextui-org/react": "^2.4.6",
    "@tanstack/react-query": "^5.51.23",
    "axios": "^1.7.3",
    "clsx": "^2.1.1",
    "date-fns": "^3.6.0",
    "framer-motion": "^11.3.23",
    "i18next": "^23.12.3",
    "i18next-browser-languagedetector": "^8.0.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-hook-form": "^7.52.2",
    "react-i18next": "^15.0.1",
    "react-router-dom": "^6.26.0",
    "zustand": "^4.5.4"
  },
  "devDependencies": {
    "@chromatic-com/storybook": "^1.6.1",
    "@eslint/js": "^9.8.0",
    "@storybook/addon-essentials": "^8.2.8",
    "@storybook/addon-interactions": "^8.2.8",
    "@storybook/addon-links": "^8.2.8",
    "@storybook/addon-onboarding": "^8.2.8",
    "@storybook/addon-styling-webpack": "^1.0.0",
    "@storybook/addon-themes": "^8.2.8",
    "@storybook/blocks": "^8.2.8",
    "@storybook/react": "^8.2.8",
    "@storybook/react-vite": "^8.2.8",
    "@storybook/test": "^8.2.8",
    "@testing-library/dom": "^10.4.0",
    "@testing-library/jest-dom": "^6.4.8",
    "@testing-library/react": "^16.0.0",
    "@testing-library/user-event": "^14.5.2",
    "@types/node": "^22.1.0",
    "@types/react": "^18.3.3",
    "@types/react-dom": "^18.3.0",
    "@vitejs/plugin-react-swc": "^3.5.0",
    "@vitest/coverage-v8": "^2.0.5",
    "autoprefixer": "^10.4.20",
    "eslint": "^9.8.0",
    "eslint-plugin-react-hooks": "^5.1.0-rc.0",
    "eslint-plugin-react-refresh": "^0.4.9",
    "eslint-plugin-storybook": "^0.8.0",
    "globals": "^15.9.0",
    "jsdom": "^24.1.1",
    "postcss": "^8.4.41",
    "storybook": "^8.2.8",
    "storybook-addon-remix-react-router": "^3.0.0",
    "tailwindcss": "^3.4.8",
    "typescript": "^5.5.3",
    "typescript-eslint": "^8.0.0",
    "vite": "^5.4.0",
    "vitest": "^2.0.5"
  }
}

Reproduction link

...

Reproduction steps

Run storybook
Access story page

System

Storybook Environment Info:

  System:
    OS: Linux 6.9 Fedora Linux 40 (Workstation Edition)
    CPU: (16) x64 12th Gen Intel(R) Core(TM) i7-1270P
    Shell: 5.9 - /usr/bin/zsh
  Binaries:
    Node: 20.11.1 - ~/.nvm/versions/node/v20.11.1/bin/node
    Yarn: 1.22.22 - ~/.nvm/versions/node/v20.11.1/bin/yarn <----- active
    npm: 10.2.4 - ~/.nvm/versions/node/v20.11.1/bin/npm
  npmPackages:
    @storybook/addon-essentials: ^8.2.8 => 8.2.8 
    @storybook/addon-interactions: ^8.2.8 => 8.2.8 
    @storybook/addon-links: ^8.2.8 => 8.2.8 
    @storybook/addon-onboarding: ^8.2.8 => 8.2.8 
    @storybook/addon-styling-webpack: ^1.0.0 => 1.0.0 
    @storybook/addon-themes: ^8.2.8 => 8.2.8 
    @storybook/blocks: ^8.2.8 => 8.2.8 
    @storybook/react: ^8.2.8 => 8.2.8 
    @storybook/react-vite: ^8.2.8 => 8.2.8 
    @storybook/test: ^8.2.8 => 8.2.8 
    eslint-plugin-storybook: ^0.8.0 => 0.8.0 
    storybook: ^8.2.8 => 8.2.8 
    storybook-addon-remix-react-router: ^3.0.0 => 3.0.0

Additional context

Some components did not break even though the JSDocs were annotated.

Conditional.tsx

Preview
Code

export interface ConditionalProps<T> {
if: T
then: JSX.Element | ((value: NonNullable<T>) => JSX.Element)
fallback?: JSX.Element | null
}

/**
* Renders the specified element if the condition is true, otherwise renders the fallback element.
*
* @template T - The type of the value being evaluated.
* @param {Object} props - The props object.
* @param {T} props.if - The value to evaluate the condition against.
* @param {React.ReactNode | ((value: T) => React.ReactNode)} props.then - The element to render if the condition is true. If it is a function, it will be called with the evaluated value.
* @param {React.ReactNode} [props.fallback=null] - The element to render if the condition is false.
*
* @example
* <Conditional
*   if={state}
*   then={<div>State is true</div>}
*   fallback={<div>State is false</div>}
* />
*
* @returns {React.ReactNode} - The rendered element.
*/
export function Conditional<T>({
fallback = null,
if: value,
then
}: ConditionalProps<T>): React.ReactNode {
const element = typeof then == 'function' ? then(value!) : then

return value ? element : fallback
}

smlimasu commented 3 weeks ago

Setting the jsdoc as the description is not a bug, it's a feature. You can overwrite this by setting an empty string as the description (see chapter description in the documentation website) at the preview, meta or story level. Or just go in and provide a meaningful description instead in one of these places.

ipetinate commented 3 weeks ago

Setting the jsdoc as the description is not a bug, it's a feature. You can overwrite this by setting an empty string as the description (see chapter description in the documentation website) at the preview, meta or story level. Or just go in and provide a meaningful description instead in one of these places.

Thanks, I figured this out after searching a lot about it in the docs.

I'm now using the following code block in my stories and it has solved the problem:

{
  "parameters": {
    "docs": { 
      "description": { 
        "component": "Description here" 
      } 
    }
  }
}

Doc reference: https://storybook.js.org/docs/api/doc-blocks/doc-block-description#writing-descriptions

But the strange thing was that some (in this case 3 components) did not add the comments with JSDocs. But anyway, I managed to solve what I thought was a problem (and it wasn't).

storybookjs / storybook