Reactの各コンポーネントにドキュメンテーションコメントを付ける

ドキュメンテーションコメントとは、関数を説明するためのコメントのことです。

Reactの各コンポーネントにドキュメンテーションコメントを付けると、
コードの可読性や保守性が向上します。
特にチーム開発や将来的なメンテナンスに役立ちます。

以下に、JSDoc形式でのReactコンポーネントのコメント例を示します。

---

例：Functional Component

tsx

/**
 * ボタンコンポーネント。
 * 任意のラベルとクリックイベントを受け取り、標準のボタンを表示します。
 *
 * @component
 * @example
 * return (
 *   <Button label="クリックしてね" onClick={() => alert('クリックされました')} />
 * )
 *
 * @param {Object} props - コンポーネントのprops
 * @param {string} props.label - ボタンに表示するテキスト
 * @param {() => void} props.onClick - ボタンがクリックされたときに呼び出される関数
 */
const Button = ({ label, onClick }: { label: string; onClick: () => void }) => {
  return <button onClick={onClick}>{label}</button>;
};

export default Button;

---

例：Propsの型にコメントを付ける場合（TypeScript）

tsx

/**
 * CardコンポーネントのProps型
 */
type CardProps = {
  /** カードタイトル */
  title: string;
  /** カード本文 */
  content: string;
  /** 非表示にするかどうかのフラグ */
  hidden?: boolean;
};

/**
 * 情報表示用のCardコンポーネント。
 * タイトルと内容を表示し、必要に応じて非表示にできます。
 *
 * @component
 */
const Card = ({ title, content, hidden = false }: CardProps) => {
  if (hidden) return null;

  return (
    <div className="card">
      <h2>{title}</h2>
      <p>{content}</p>
    </div>
  );
};

export default Card;

---

コメント記述のポイント

対象	コメントに含めるべき情報
コンポーネント全体	目的、主な使用方法、例、注意点など
Props	型、必須かどうか、デフォルト値、用途など
メソッド（カスタムフック等）	返り値、引数、用途、使い方

Reactのカスタムフック（Custom Hook）にJSDocスタイルでコメントを付ける例

---

🔁 カスタムフックの例：useToggle

tsx

import { useState, useCallback } from 'react';

/**
 * 真偽値のトグルを管理するカスタムフック。
 *
 * @returns {[boolean, () => void, (value: boolean) => void]} - 
 * - 現在の状態 (`boolean`)
 * - 状態をトグルする関数
 * - 状態を明示的に設定する関数
 *
 * @example
 * const [isOpen, toggleOpen, setOpen] = useToggle(false);
 *
 * return (
 *   <>
 *     <button onClick={toggleOpen}>{isOpen ? '閉じる' : '開く'}</button>
 *     {isOpen && <div>モーダル内容</div>}
 *   </>
 * );
 */
export function useToggle(initialValue: boolean = false): [
  boolean,
  () => void,
  (value: boolean) => void
] {
  const [value, setValue] = useState<boolean>(initialValue);

  const toggle = useCallback(() => setValue(v => !v), []);
  const set = useCallback((val: boolean) => setValue(val), []);

  return [value, toggle, set];
}

---

💡 コメントのポイント

要素	説明例
概要説明	どのような動作をするフックか簡潔に説明
@returns	配列などの場合は要素ごとの説明をコメントに含める
@example	実際の使用例を書くと理解しやすくなる
@param	引数がある場合は詳細を記述（例：initialValue）

---

🧠 よくあるカスタムフックと目的例

フック名	用途
useToggle	true/false の切り替え
useLocalStorage	ローカルストレージとの同期
usePrevious	前の状態の保持
useDebounce	入力値などのデバウンス（遅延処理）