记录私有泛型类型的公共具体变体

In 我的另一个问题 https://stackoverflow.com/q/70102943/857390，我问如何只公开公开一个具体的变体（Foo<u32>）私有泛型类型（Foo<T>）。建议的解决方案如下：

mod internal {
    /// Private documentation of `Foo`.
    pub struct Foo<X> {
        /// Private documentation of `x`.
        pub x: X,
    }

    impl Foo<u32> {
        pub fn foo() -> u32 {
            32
        }
    }

    impl Foo<u8> {
        pub fn foo() -> u8 {
            8
        }
    }
}

/// Public documentation of `FooBar`.
pub type FooBar = internal::Foo<u32>;

这是有效的，因为公共 API 只包含FooBar， 但不是Foo。然而，从文档的角度来看，它是缺乏的。这是输出cargo doc for FooBar:

如你看到的，

• 私人类型Foo出现在文档中，但它不是链接，并且Foo没有单独的
• 私人文件均不Foo，也不属于Foo.x显示

因此，该文档并不是真正有用。显然我可以在文档中添加更多信息FooBar，但这仍然不会使文档成为FooBar看起来像普通的struct.

通过这种方法，文档FooBar显然不如“等效”定义FooBar像这样：

/// Public documentation of `FooBar`.
pub struct FooBar {
    /// Public documentation of `x`.
    x: u32,
}

我将“等效”放入引号中，因为我确实假设从编译器的角度（显然是cargo doc），这两个定义FooBar是完全不同的。我的问题是我的文档的读者不必关心这种差异。

在这种情况下有没有办法实现“自然”文档？

我很高兴使用完全不同的方法来隐藏通用的Foo定义（如果有必要的话）。

您可以使用#[cfg(doc)]伪造该物品：

#[cfg(not(doc))]
pub type FooBar = internal::Foo<u32>;
#[cfg(doc)]
/// Public documentation of `FooBar`.
pub struct FooBar {
    /// Public documentation of `x`.
    pub x: u32,
}

但这将隐藏所有impls（除非您也复制它们）和重复的代码。所以，不要这样做。