如何让rustdoc从子模块链接到私有项？

我正在为一个拆分为多个子模块的二进制项目编写文档，src目录下有两个文件：

src/main.rs #

//! # My Lovely Crate
//! 
//! I can reference [`sub::Public`].
//! But, can't reference [`sub::Private`].

mod sub;

src/sub.rs #

//! # My Lovely Sub

/// This struct is public.
pub struct Public {
    a: usize,
}

/// This struct is private.
struct Private {
    b: usize,
}

执行命令cargo doc --document-private-items时，生成的文档包含sub模块中的两个结构体，但sub::Private的引用无法解析，未生成链接。请问是否有解决方法？或是我操作有误？

这不是操作错误，是cargo doc的默认行为：即使生成了私有项的文档，跨模块的私有项引用依然不会自动生成链接，因为私有项本身不属于对外暴露的API范畴。

有两种可行的解决办法：

• 调整可见性（推荐）：将Private结构体的可见性改为pub(crate)（ crate内全局可见），这样既不会把结构体暴露到 crate 外部，又能让 crate 内部的文档引用正常生成链接。修改后的src/sub.rs代码如下：

  /// This struct is private.
  pub(crate) struct Private {
      b: usize,
  }
  

  重新运行cargo doc --document-private-items后，sub::Private的引用就能正常生成链接。

• 显式指定文档路径：如果不想修改代码可见性，可以手动在文档链接中指定私有项的完整路径，比如把main.rs中的注释改成：

  //! But, can reference [`sub::Private`](crate::sub::Private).
  

  这种方式的缺点是，一旦私有项的路径或名称发生变化，链接会失效，维护成本较高。

内容的提问来源于stack exchange，提问作者Samuel Hapak