Тестирование файлов справки по запросу

Сведения о файлах справки по запросу тестирования

Тестируйте файлы справки по запросу, отрисовав их как Markdown, чтобы убедиться, что они действительны перед отправкой в репозиторий CodeQL или с их помощью в сканировании кода.

Справка по запросу — это документация, которая сопровождает запрос, чтобы объяснить, как работает запрос, а также предоставить сведения о потенциальной проблеме, которую идентифицирует запрос. Рекомендуется написать справку по запросу для всех новых запросов. Дополнительные сведения см. в статье "Участие в CodeQL в репозитории CodeQL.

CodeQL CLI включает команду для тестирования справки по запросу и отрисовки содержимого в виде markdown, чтобы можно было легко просмотреть содержимое в интегрированной среде разработки. Используйте команду для проверки файлов справки по запросу перед отправкой их в репозиторий CodeQL или совместного использования с другими пользователями. Начиная с CodeQL CLI 2.7.1, вы также можете включить справку по запросу markdown, отображаемую в файлах SARIF, созданных во время анализа CodeQL для отображения справки по запросу в пользовательском интерфейсе сканирования кода. Дополнительные сведения см. в разделе Анализ кода с помощью запросов CodeQL.

Необходимые компоненты

• Файл справки запроса (.qhelp) должен содержать сопровождающий файл запроса (.ql) с идентичным базовым именем.
• Файл справки запроса должен соответствовать стандартной структуре и стилю справки по запросу. Дополнительные сведения см. в руководстве по стилю справки по запросу в репозитории CodeQL.

Запущена codeql generate query-help

Вы можете протестировать файлы справки по запросу, выполнив следующую команду:

codeql generate query-help <qhelp|query|dir|suite> --format=<format> [--output=<dir|file>]

Для этой команды <qhelp|query|dir|suite> должен быть путь к .qhelp файлу, путь .ql к файлу, путь к каталогу, содержащий запросы и файлы справки запросов, или путь к набору запросов.

Необходимо указать параметр, определяющий --format способ отрисовки справки по запросу. В настоящее время необходимо указать markdown , чтобы отобразить справку запроса как markdown.

Параметр --output определяет путь к файлу, в котором будет сохранена помощь отрисованного запроса.

• Для каталогов, .qhelp содержащих файлы или наборы запросов, определяющие один или несколько .qhelp файлов, необходимо указать --output каталог. Имена файлов в выходном .qhelp каталоге будут производными от имен файлов.
• Для одного .qhelp или .ql файлов можно указать --output параметр. Если вы не указываете выходной путь, функция справки по отрисованному запросу записывается в stdout.

Полные сведения обо всех параметрах, которые можно использовать при тестировании файлов справки запросов, см. в разделе "создание справки по запросу".

Результаты

При выполнении команды CodeQL пытается отобразить каждый .qhelp файл с сопутствующим .ql файлом. Для отдельных файлов отрисованное содержимое будет напечатано stdout , если параметр не указан --output . Во всех других случаях использования отрисованное содержимое сохраняется в указанном выходном пути.

По умолчанию CodeQL CLI выводит предупреждение, если:

• Любая справка по запросу является недопустимой, а также описание недопустимых элементов справки запроса
• Все .qhelp файлы, указанные в команде, не имеют того же базового имени, что и сопровождающий .ql файл.
• Все .ql файлы, указанные в команде, не имеют того же базового имени, что и сопровождающий .qhelp файл.

Вы можете сообщить CodeQL CLI об обработке этих предупреждений, включив --warnings параметр в команду. Дополнительные сведения см. в разделе создание справки по запросу.

Дополнительные материалы

• "Запрос файлов справки"