7

在我的另一个问题中，我询问了如何仅公开公开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 docfor的输出FooBar：

Cargo 文件截图

如你看到的，

  • 私有类型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定义。

4

1 回答 1

0

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

于 2021-12-05T14:03:06.853 回答