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

【问题标题】：Documenting a public concrete variant of a private generic type记录私有泛型类型的公共具体变体
【发布时间】：2022-01-10 13:34:29
【问题描述】：

在another question of mine 中，我询问了如何仅公开公开私有泛型类型 (Foo<T>) 的具体变体 (Foo<u32>)。建议的解决方案如下：

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 对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 定义。

【问题讨论】：

那为什么我不同意这个技巧，Rust pub 可见性规则并不完美，你使用一个技巧给用户一个公共类型但它是一个私有类型，错了，你的类型应该都是 pub to从用户是否需要一个文档开始。 Tl;DR: semver 欺骗 sux 并伤害用户，只需按照应有的方式制作 pub item pub
这能回答你的问题吗？ How to generate documentation for private items
@Stargateur：正如我所说，我对完全不同的方法持开放态度。但是，请注意，我的实际用例中的类型要复杂得多，因此减少样板代码和代码重复对我来说很重要。
@Stargateur：另外，感谢建议的副本。我认为它不符合我的问题，因为我正在尝试记录 public 类型。
在给定的示例中，字段x 是私有的——那么您为什么希望它出现在文档中？

标签： generics rust access-modifiers rustdoc

【解决方案1】：

您可以使用#[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（除非您也复制它们）并重复代码。所以，不要那样做。

【讨论】：