ドキュメントとコードの変更の同期

Copilot Chat は、コードのドキュメントを最新の状態に保つのに役立ちます。

この記事の内容

コードに対する変更でドキュメントを最新の状態に保つのは難しい場合があります。 しかし、コードベースを維持し、開発者がコードを効果的に操作できるようにするためには、適切なドキュメントが不可欠です。 Copilot Chat は、既存のコード ドキュメントの更新を支援できます。

シナリオ例

カテゴリ名で製品を取得する TypeScript 関数があり、しかしドキュメントが古くなっているシナリオを想像してみてください。

/**
 * Retrieves all products belonging to a specific category.
 *
 * @param categoryId - The unique identifier of the product category
 * @returns Promise that resolves to an array of Product objects
 *
 * @example
 * const products = await getByCategoryName(5);
 * // Returns: [{id: 1, name: "Product 1", categoryId: 5}, ...]
 *
 * @throws {PrismaClientKnownRequestError} If database query fails
 * @see {@link https://www.prisma.io/docs/reference/api-reference/prisma-client-reference#findmany}
 */
async getByCategoryName(categoryId: number, page = 1, pageSize = 10): Promise<Products[]> {
  return await prisma.products.findMany({
    where: { categoryId },
    skip: (page - 1) * pageSize,
    take: pageSize,
    include: {
      reviews: {
        orderBy: { date: 'desc' },
        take: 5,
      },
    },
  });
}

プロンプトの例

現在のコードに従ってドキュメントを更新するよう、Copilot Chat に依頼できます。

Update the existing documentation for the getByCategoryName function to reflect the current implementation.

応答の例

メモ

次の応答は例です。 Copilot Chat の応答は非決定的であるため、ここで示したものと��異なる応答が返される可能性があります。

Copilot は、getByCategoryName 関数の更新されたドキュメントを作成することを説明します。 その後、更新されたドキュメントを提供します。それには、page と pageSize パラメーター、およびスローされる可能性がある PrismaClientKnownRequestError エラーが含まれるようになっています。

次に例を示します。

/**
 * Retrieves all products belonging to a specific category with pagination and recent reviews.
 *
 * @param categoryId - The unique identifier of the product category
 * @param page - The page number for pagination (default: 1)
 * @param pageSize - Number of products per page (default: 10)
 * @returns Promise that resolves to an array of Product objects with their 5 most recent reviews
 *
 * @example
 * const products = await getByCategoryName(5, 2, 20);
 * // Returns: [{id: 1, name: "Product 1", categoryId: 5, reviews: [...5 recent reviews]}, ...]
 *
 * @throws {PrismaClientKnownRequestError} If database query fails
 * @see {@link https://www.prisma.io/docs/reference/api-reference/prisma-client-reference#findmany}
 */

参考資料