Советы по Rust ｜ Улучшите комментарии к документам с помощью макроса атрибута `#[doc]`

задняя часть Rust

Монтажер: Чжан Ханьдун

Примечание. Эта статья основана на исходном тексте, а также представляет другой контент.

Знакомство с новыми функциями макросов свойств

отRust 1.54Первоначально макросы свойств добавляли поддержку функциональных макросов.

Функционально-подобные макросы могут быть основаны наmacro_rules！Макрос объявления также может быть чем-то вродеmacro！(...)Процедурные макросы, которые называются именно так. Это неплохо для комментариев к документации. Если README вашего проекта является хорошим комментарием к документации, вы можете использоватьinclude_str!непосредственно включать его содержание. Ранее различные обходные пути позволяли использовать аналогичную функциональность, но от1.54Начнем с того, что он более эргономичен.

#![doc = include_str!("README.md")]

Если вы видели некоторые проекты с открытым исходным кодом Rust, вам следуетlib.rsВы видели кучу комментариев к документации? Эти комментарии настолько длинные, что реальный код оказывается внизу. С помощью этой функции такие проблемы могут быть решены.

macro_rules! make_function {
    ($name:ident, $value:expr) => {
        // 这里使用 concat! 和 stringify! 构建文档注释
        #[doc = concat!("The `", stringify!($name), "` example.")]
        ///
        /// # Example
        ///
        /// ```
        #[doc = concat!(
            "assert_eq!(", module_path!(), "::", stringify!($name), "(), ",
            stringify!($value), ");")
        ]
        /// ```
        pub fn $name() -> i32 {
            $value
        }
    };
}

make_function! {func_name, 123}

Также можно создавать комментарии к документации, встраивая вызовы макросов в свойства, подобные этому. Вы можете сравнить расширенный код:

///The `func_name` example.
///
/// # Example
///
/// ```
///assert_eq!(doc_attr::func_name(), 123);
/// ```
pub fn func_name() -> i32 {
    123
}

В этом случае документ также можно использовать повторно. Конечно, вы также можете расширить другие варианты использования.

Другое использование

существуетЭта статья друга из иностранного сообществаВ , он перечислил некоторые приложения.

Расширьте возможности тестирования с помощью тестирования документов

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

/// ```compile_fail
#[doc = include_str!("compile_fail.rs")]
/// ```
mod doc_test {}

Вы можете поставить соответствующие тесты вcomplile_fail.rs, а затем включите его с помощью комментария документа, чтобы тесты были доступны, когда Cargo их выполняет. И в целом повышенная читаемость и ремонтопригодность кода Rust. Точно так же вы также можете проверить панику и т. Д.

Мы также не хотим, чтобы такие комментарии появлялись в документации конечного пользователя или в скомпилированном файле, поэтому нам нужно использоватьcfg(doctest)чтобы скрыть это:

#[cfg(doctest)]
/// ```compile_fail
#[doc = include_str!("compile_fail.rs")]
/// ```
mod doc_test {}
Категории