Предупреждение Clippy в документации по вызовам макросов

Вопрос или проблема

У меня есть следующий код для бенчмарков на 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 в текущей конфигурации не позволяют документировать функции, создаваемые с помощью макросов, существуют методы для управления предупреждениями о недостающей документации. Вы можете выбрать подход, который лучше всего соответствует вашим требованиям к проекту, обеспечивая при этом высокое качество кода.

Оцените материал
Добавить комментарий

Капча загружается...