Документация разработчика обычно включает описание в каждом файле. Эти описания могут устареть, что приведет к путанице и неверной информации. Чтобы предотвратить это, вы можете автоматизировать обнаружение устаревших описаний в вашей документации, используя немного искусственного интеллекта и GenAIScript.

Маркдаун и фронтовая тема

Многие системы документации используют формат уценки для написания документации и заголовок «frontmatter» для хранения метаданных. Вот пример файла уценки с фронтальной надписью:

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

# My Document

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Цель состоит в том, чтобы создать скрипт, который определяет, когда поле описания во вступительной заставке устарело.

Сценарий

GenAIScript предназначен для работы с файлами и предоставляет специальную переменную env.files, содержащую список файлов для анализа. Вы можете использовать эту переменную для включения файлов в контекст с помощью функции def. Мы ограничиваем каждый файл 2000 токенами, чтобы избежать разрыва содержимого больших файлов.

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

Следующий шаг — дать задание скрипту. В этом случае необходимо проверить совпадение содержимого и поля описания во вступительной части.

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

Наконец, мы используем встроенную функцию генерации диагностики, чтобы создавать ошибку для каждого устаревшего описания.

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

Запуск в коде Visual Studio

Как только вы сохраните этот скрипт в своем рабочем пространстве, вы сможете выполнить его для файла или папки через контекстное меню
выбрав Выполнить GenAIScript....

Автоматизация

Вы можете автоматически запустить этот инструмент для файлов документации, чтобы выявить устаревшие описания с помощью командной строки.

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

Этот скрипт можно интегрировать в ваш конвейер CI/CD для автоматизации процесса обнаружения.