如何为Rust类型别名生成完整文档？类型别名文档缺失求解

问题背景 #

我开发的Rust库中有一款压缩器，支持两种API不同但数据模型、通用逻辑一致的模式。为遵循DRY原则复用代码，采用了如下结构：

struct BaseCompressor<M: Mode> {...}
impl<M: Mode> BaseCompressor<M> {
  /// some docs...
  pub fn header(...) -> ... {...}
}

pub type CompressorA = BaseCompressor<ModeA>;
impl CompressorA {
  /// some docs...
  pub fn chunk(...) -> ... {...}
}

pub type CompressorB = BaseCompressor<ModeB>;
impl CompressorB {
  /// some docs...
  pub fn data_page(...) -> ... {...}

该结构能让CompressorA和CompressorB共享数据成员与header方法逻辑，但生成的文档中这两个类型没有展示共享的方法内容。我不想将BaseCompressor暴露到公共API，需要解决文档生成问题或优化结构。

解决方案 #

1. 使用#[doc(inline)]合并文档 #

给公共类型别名添加#[doc(inline)]属性，可将私有BaseCompressor的文档自动合并到别名文档中，同时保留别名自身的方法实现。

修改后的代码示例：

struct BaseCompressor<M: Mode> {...}
impl<M: Mode> BaseCompressor<M> {
  /// 生成压缩器头部信息
  pub fn header(...) -> ... {...}
}

#[doc(inline)]
pub type CompressorA = BaseCompressor<ModeA>;
impl CompressorA {
  /// 处理数据块
  pub fn chunk(...) -> ... {...}
}

#[doc(inline)]
pub type CompressorB = BaseCompressor<ModeB>;
impl CompressorB {
  /// 处理数据页
  pub fn data_page(...) -> ... {...}
}

生成的文档会同时展示header方法和各自的专属方法，且BaseCompressor仍保持私有。

2. 手动转发方法（精细控制） #

如果需要对文档或方法调用做更精细的控制，可以在公共类型的impl块中手动转发BaseCompressor的方法，并保留或补充文档注释。

示例：

impl CompressorA {
  /// 处理数据块
  pub fn chunk(...) -> ... {...}

  /// 生成压缩器头部信息
  pub fn header(...) -> ... {
    <Self as BaseCompressor<ModeA>>::header(...)
  }
}

这种方式虽然需要编写少量转发代码，但能完全控制每个方法的文档展示，避免暴露底层的BaseCompressor。

3. 宏批量生成转发代码 #

当需要转发的方法较多时，可通过宏自动生成转发逻辑，减少重复代码：

macro_rules! impl_shared_compressor_methods {
    ($compressor:ty, $mode:ty) => {
        impl $compressor {
            /// 生成压缩器头部信息
            pub fn header(...) -> ... {
                BaseCompressor::<$mode>::header(...)
            }
            // 可添加更多需要转发的共享方法
        }
    };
}

// 为每个压缩器类型生成共享方法的转发
impl_shared_compressor_methods!(CompressorA, ModeA);
impl_shared_compressor_methods!(CompressorB, ModeB);

// 保留各自的专属方法实现
impl CompressorA {
  /// 处理数据块
  pub fn chunk(...) -> ... {...}
}

impl CompressorB {
  /// 处理数据页
  pub fn data_page(...) -> ... {...}
}

宏的方式既保证了代码复用，又能让每个公共压缩器类型的文档完整展示所有方法。

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