macro-vis

此包提供了一种属性，用于定义具有适当可见性和作用域的 macro_rules! 宏。

macro_rules! 宏的默认作用域和公开规则是晦涩难懂的：它们的行为与其他 Rust 编程语言中的项不同，引入了一些难以克服的令人沮丧的限制。这个问题最终将通过一种称为 声明性宏 2.0 的新类型宏得到解决，但该功能已经停滞不前多年，可能还需要几年才能在稳定版 Rust 中出现。

因此，这个包就应运而生。它允许你在任何 macro_rules! 宏上放置 #[macro_vis] 或 #[macro_vis(VISIBILITY)]，并使其与其他支持可见性修饰符的项（如结构体、枚举、函数等）一样被处理。它与本地包和公共宏一起工作，有效地取代了 #[macro_use] 和 #[macro_export]。

有关示例和用法，请参阅 #[macro_vis] 的文档。

uncommon_codepoints 警告

如果您使用这个库，将收到 uncommon_codepoints 警告，因此您可能希望在crate根目录下放置它

#![allow(uncommon_codepoints)]

记录公共宏

如果使用Nightly编译器运行，公共宏的文档可以稍作改进。要启用此功能，您必须首先将此属性添加到crate根目录

#![cfg_attr(doc_nightly, feature(decl_macro, rustc_attrs))]

然后，您可以使用设置 doc_nightly cfg 来构建，无论是本地使用 RUSTDOCFLAGS="--cfg doc_nightly" cargo +nightly doc 还是docs.rs通过将其添加到您的 Cargo.toml

[package.metadata.docs.rs]
rustdoc-args = ["--cfg", "doc_nightly"]

它的工作原理

使非 pub 宏正常工作的技巧很简单；我们只是在定义之后使用宏，使其被视为一个项目。原始宏被重命名为一个随机生成的标识符，这样就不能通过常规代码访问。此代码

#[macro_vis(pub(crate))]
macro_rules! example_macro { () => {}; }

展开成类似的东西

macro_rules! __example_macro_2994407750278293171 { () => {}; }
pub(crate) use __example_macro_2994407750278293171 as example_macro;

pub 宏的工作原理相同，但对宏使用 #[macro_export] 并确保它不会出现在文档中

#[doc(hidden)]
#[macro_export]
macro_rules! __example_macro_2994407750278293171 { () => {}; }
pub use __example_macro_2994407750278293171 as example_macro;

但是，由于重新导出 #[doc(hidden)] 项本身也是 #[doc(hidden)]，因此宏根本不会出现在文档中。为了解决这个问题，库根据Nightly是否可用采用两种解决方案

• 当 doc_nightly 未启用时，库发出一个公共函数，其名称是宏名称与拉丁字母回转点（ǃ）的连接，该字符看起来几乎与用于调用宏的感叹号相同。这样做是为了避免与具有相同名称的其他函数和宏文档双重的名称冲突。然而，它有一个缺点，即即使宏不是函数，它也会在文档中显示为函数，并且它与重新导出不兼容。

• 当 doc_nightly 启用 时，库将宏改为宏 2.0 风格的 pub macro，它默认遵守正确的可见性规则。与先前的解决方案不同，此解决方案将宏显示在正确的文档部分，并以正确的文本颜色显示，同时它还与内联重新导出正常工作。缺点是它不在稳定版上工作，因此在未来有更大的中断风险。

MSRV

此crate的最小支持Rust版本是1.53，这是第一个稳定 non_ascii_idents 的版本。目前认为将其提高是一个破坏性更改。

致谢

此crate中的大多数想法都是通过 Daniel Henry-Mantilla 发现并展示给我的，因此大部分功劳归功于他们。

许可证：MIT