Sincronización de documentación con cambios de código

Mantener la documentación actualizada puede resultar difícil con los cambios en el código. Sin embargo, es esencial contar con una documentación óptima para mantener los códigos base y asegurarse de que los desarrolladores puedan trabajar de forma eficaz con el código. El Copilot Chat puede ayudar a actualizar la documentación de código existente.

Escenario de ejemplo

Imagina un escenario en el que tienes una función de TypeScript que recupera productos por nombre de categoría, pero la documentación no está actualizada.

/**
 * 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,
      },
    },
  });
}

Ejemplos de indicaciones

Puedes pedir al Copilot Chat que actualice la documentación en función del código actual.

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

Respuesta de ejemplo

Copilot explica que va a crear la documentación actualizada para la función getByCategoryName. A continuación, proporciona la documentación actualizada, que ahora incluye los parámetros page y pageSize, así como el error PrismaClientKnownRequestError que puede producirse.

Por ejemplo:

/**
 * 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}
 */

Información adicional

• "Solicitud de ingeniería para GitHub Copilot"
• "Procedimientos recomendados para usar GitHub Copilot"