Вопрос или проблема
У меня есть следующий код для бенчмарков на Rust.
criterion_group!(benches, criterion_benchmark);
criterion_main!(benches);
Настройка линтера Clippy в cargo.toml
[lints]
rust.missing_docs = "warn"
При выполнении команды cargo clippy --workspace --all-targets
У меня есть следующее предупреждение.
warning: missing documentation for a function
--> benches/b.rs:13:1
|
13 | criterion_group!(benches, criterion_benchmark);
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
После добавления документации, как предложено линтером.
/// doc
criterion_group!(benches, criterion_benchmark);
Предупреждение сохраняется.
warning: unused doc comment
--> benches/b.rs:13:1
|
13 | /// doc
| ^^^^^^^ rustdoc does not generate documentation for macro invocations
Я выяснил, что документирование вызовов макросов отличается. Но тот, который я использую, предоставляет библиотека.
Как это исправить?
Вы не можете, но есть обходное решение. Ваши вызовы макросов cargo expand
преобразуются в следующее:
pub fn benches() {
let mut criterion: ::criterion::Criterion<_> =
::criterion::Criterion::default().configure_from_args();
criterion_benchmark(&mut criterion);
}
fn main() {
benches();
::criterion::Criterion::default()
.configure_from_args()
.final_summary();
}
Здесь функция benches
не документирована. Документация рядом с вызовами макросов не документирует функцию(и), которые они создают. Я не вижу способа сделать так, чтобы ваша созданная функция была документирована (кроме как подать PR в criterion
, чтобы добавить поддержку документации для макроса).
Мое предложение — вставить #![allow(missing_docs)]
в начало вашего файла(ов) бенчмарков, чтобы exempt их от линтера. Если вы хотите прокомментировать ваш макрос, вы можете использовать обычный комментарий, начинающийся с //
.
К сожалению, вы не можете применить документацию к функции, созданной макросом, если автор макроса специально не добавил поддержку для этого. Однако вы по крайней мере можете ограничить предупреждение о недостающей документации, поместив группу критериев в собственный модуль.
#![deny(missing_docs)]
//! документация крейта
use criterion::{criterion_group, criterion_main, Criterion};
fn criterion_benchmark(c: &mut Criterion) {}
mod groups {
#![allow(missing_docs)]
use super::*;
criterion_group!(benches, criterion_benchmark);
}
criterion_main!(groups::benches);
Ответ или решение
Устранение предупреждений Clippy при использовании макросов в Rust
При работе с Rust и его инструментами, такими как Clippy, разработчики могут столкнуться с предупреждениями о недостающей документации при использовании макросов. В данном руководстве мы рассмотрим, почему возникает предупреждение Clippy о недостающей документации и как с ним справиться, используя примеры и рабочие методы.
Ситуация
Вы написали код для бенчмаркинга, используя библиотеку Criterion, и вашу конфигурацию Clippy настроили на выдачу предупреждений в случае недостатка документации:
criterion_group!(benches, criterion_benchmark);
criterion_main!(benches);
В вашем файле Cargo.toml
имеется следующий фрагмент:
[lints]
rust.missing_docs = "warn"
После выполнения команды cargo clippy --workspace --all-targets
появляется следующее предупреждение:
warning: missing documentation for a function
---> benches/b.rs:13:1
|
13 | criterion_group!(benches, criterion_benchmark);
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Поведение Clippy при документировании макросов
Когда вы добавляете документацию прямо над вызовом макроса:
/// doc
criterion_group!(benches, criterion_benchmark);
Это не устраняет предупреждение, потому что Clippy сообщает:
warning: unused doc comment
---> benches/b.rs:13:1
|
13 | /// doc
| ^^^^^^^ rustdoc does not generate documentation for macro invocations
Дело в том, что документация, добавленная перед вызовом макроса, не отражается на функциях, генерируемых этим макросом. Rustdoc не поддерживает документирование функций, созданных с помощью макросов.
Альтернативные решения
1. Игнорирование предупреждения
Одним из простых решений является игнорирование предупреждений о недостающей документации, добавив в начале файла следующее:
#![allow(missing_docs)]
Этот подход отключит все предупреждения, связанные с отсутствием документации, в текущем модуле.
2. Структурирование кода
Более изящным подходом будет размещение вызова макроса в отдельном модуле для изоляции предупреждений:
#![deny(missing_docs)]
//! Документация для всего файла
use criterion::{criterion_group, criterion_main, Criterion};
fn criterion_benchmark(c: &mut Criterion) {}
mod groups {
#![allow(missing_docs)]
use super::*;
criterion_group!(benches, criterion_benchmark);
}
criterion_main!(groups::benches);
Таким образом, вы сохраняете строгие требования к документации для остальных частей вашего кода, одновременно управляя предупреждениями о недостающей документации для определенного модуля.
Заключение
Хотя Clippy и Rustdoc в текущей конфигурации не позволяют документировать функции, создаваемые с помощью макросов, существуют методы для управления предупреждениями о недостающей документации. Вы можете выбрать подход, который лучше всего соответствует вашим требованиям к проекту, обеспечивая при этом высокое качество кода.