docsplay：文档注释 - 显示

这个库是 displaydoc 的分支，提供了一个方便的 derive 宏，用于为标准库的 core::fmt::Display trait 实现。

[dependencies]
docsplay = "0.1"

编译器支持：需要 rustc 1.56+

示例

与来自 Error derive 宏的 thiserror 的展示一起，以传播来自 io::Error 的源位置，使用 #[source] 属性

use std::io;
use docsplay::Display;
use thiserror::Error;

#[derive(Display, Error, Debug)]
pub enum DataStoreError {
    /// data store disconnected
    Disconnect(#[source] io::Error),
    /// the data for key `{0}` is not available
    Redaction(String),
    /// invalid header (expected {expected:?}, found {found:?})
    InvalidHeader {
        expected: String,
        found: String,
    },
    /// unknown data store error
    Unknown,
}

let error = DataStoreError::Redaction("CLASSIFIED CONTENT".to_string());
assert!("the data for key `CLASSIFIED CONTENT` is not available" == &format!("{}", error));

请注意，尽管 io::Error 实现了 Display，我们并没有将其添加到 DataStoreError::Disconnect 的生成消息中，因为它已经通过 #[source] 属性提供。有关避免错误报告中重复的更多信息，请参阅 rust 博客 此处。

详细信息

• 如果您在每个变体上提供如示例中所示的文档字符串注释，则为您枚举生成 fmt::Display 实现。 Display derive 宏支持从错误中插值字段的简写
  • /// {var} ⟶ write!("{}", self.var)
  • /// {0} ⟶ write!("{}", self.0)
  • /// {var:?} ⟶ write!("{:?}", self.var)
  • /// {0:?} ⟶ write!("{:?}", self.0)
  • /// {0.foo()} ⟶ write!("{}", self.0.foo())
  • /// {0.foo():?} ⟶ write!("{:?}", self.0.foo())
• 这同样适用于结构体和泛型类型

/// oh no, an error: {0}
#[derive(Display)]
pub struct Error<E>(pub E);

let error: Error<&str> = Error("muahaha i am an error");
assert!("oh no, an error: muahaha i am an error" == &format!("{}", error));

• 可以在 derive 旁边添加两个可选属性到您的类型

  • #[ignore_extra_doc_attributes] 使宏忽略第一个之后的任何文档注释属性（或 /// 行）。

  • #[prefix_enum_doc_attributes] 将您的枚举本身的文档注释消息与每个变体的消息合并，格式为 enum: variant。当添加到枚举时，枚举的文档注释成为必填。当添加到任何其他类型时，它没有效果。

• 如果您想要一个独立的文档注释，可以在变体或结构体上使用 #[display("...") 属性来覆盖它。