Sincronizando a documentação com alterações de código

O Copilot Chat pode ajudar a manter a documentação do código atualizada.

Neste artigo

Pode ser difícil manter a documentação atualizada com alterações no código. No entanto, uma boa documentação é essencial para manter as bases de código e garantir que os desenvolvedores possam trabalhar efetivamente com o código. O Copilot Chat pode ajudar a atualizar a documentação de código existente.

Cenário de exemplo

Imagine um cenário em que você tem uma função TypeScript que recupera produtos por nome de categoria, mas a documentação está desatualizada.

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

Solicitação de exemplo

Você pode solicitar que o Copilot Chat atualize a documentação de acordo com o código atual.

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

Exemplo de resposta

Note

A resposta a seguir é um exemplo. Respostas do Copilot Chat são não determinísticas, portanto, você pode obter uma resposta diferente da mostrada aqui.

O Copilot explica que criará a documentação atualizada para a função getByCategoryName. Em seguida, ele fornece a documentação atualizada, que agora inclui os parâmetros page e pageSize, bem como o erro PrismaClientKnownRequestError que pode ser gerado.

Por exemplo:

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

Leitura adicional