A documentação do desenvolvedor normalmente inclui uma descrição em cada arquivo. Essas descrições podem ficar desatualizadas, gerando confusão e informações incorretas. Para evitar isso, você pode automatizar a detecção de descrições desatualizadas em sua documentação usando um pouco de IA e GenAIScript.

Markdown e frontmatter

Muitos sistemas de documentação usam o formato markdown para escrever documentação e um cabeçalho 'frontmatter' para armazenar metadados. Aqui está um exemplo de arquivo markdown com frontmatter:

---
title: "My Document"
description: "This is a sample document."
---

# My Document

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

O objetivo é criar um script que detecte quando o campo de descrição no frontmatter está desatualizado.

O roteiro

GenAIScript foi projetado para ser executado em arquivos e fornece uma variável especial env.files que contém a lista de arquivos a serem analisados. Você pode usar esta variável para incluir os arquivos no contexto usando a função def. Limitamos cada arquivo a 2.000 tokens para evitar a explosão do conteúdo em arquivos grandes.

// Define the file to be analyzed
def("DOCS", env.files, { endsWith: ".md", maxTokens: 2000 })

A próxima etapa é atribuir uma tarefa ao script. Neste caso, verifique se o campo de conteúdo e descrição no frontmatter correspondem.

// Analyze the content to detect outdated descriptions
$`Check if the 'description' field in the front matter in DOCS is outdated.`

Finalmente, aproveitamos o recurso integrado de geração de diagnóstico para criar um erro para cada descrição desatualizada.

// enable diagnostics generation
$`Generate an error for each outdated description.`

Executando no código do Visual Studio

Depois de salvar este script em sua área de trabalho, você poderá executá-lo em um arquivo ou pasta através do menu de contexto
selecionando Executar GenAIScript....

Automação

Você pode executar esta ferramenta automaticamente em seus arquivos de documentação para identificar descrições desatualizadas usando o cli.

npx --yes genaiscript run detect-outdated-descriptions **/*.md

Este script pode ser integrado ao seu pipeline de CI/CD para automatizar o processo de detecção.