能否为一个私有函数生成文档？

Question

能否为一个私有函数生成文档？

rustdocumentationdocumentation-generationrustdoc

3

如何强制 Rustdoc 对单个私有函数进行文档化？

我的项目中有很多私有函数，我不希望它们成为生成的 Rustdoc 输出（使用命令）。对于库用户来说，阅读这些私有函数是没有必要的。然而，有一个私有函数应该包含在生成的 Rustdoc 输出中。解释这个私有函数将帮助库用户理解整个 Rust 库。但是，我仍然不希望用户直接调用这个函数（因此它是私有的）。

我知道有一个命令行选项

--document-private-items，但我不想为许多其他私有函数编写文档。
是否有属性或命令行开关可强制文档化生成这一个私有函数？
我希望有一个与 #[doc(hidden)] 相反的属性，如 #[doc(force)] 、 #[doc(show)] 、 #[not(doc(hidden))] 等。

- JamesThomasMoon

1

我认为目前由于这个开放问题，这是不可能的。 - frankenapps

感谢 @frankenapps。我在 https://github.com/rust-lang/rust/issues/60884#issuecomment-1212480451 留下了评论。 - JamesThomasMoon

“解释这个私有函数将帮助库用户理解整个 Rust 库。” 这听起来像是首页或模块文档，没有特别提到私有方法。它感觉像是一个 XY 问题。更多关于情况的细节会有所帮助。 - Schwern

感谢@Schwern，"XY问题"是一个有趣的链接！我已经按照你的建议解决了这个问题；在模块级别添加文档。但我对Rust文档中更大的问题/需求很好奇；允许选择性地为通常不包含在文档中的内容（最常见的是私有函数）提供文档。 - JamesThomasMoon

1

这就是自由格式文档的用途。私有函数对用户隐藏，因为它们随时可能发生变化。如果您对它们进行文档记录，它们将成为已发布的接口的一部分，即对用户的承诺，并且应该是公共的。Martin Fowler已经写过关于"发布与私有"（published vs private）的重要性文章。（https://www.martinfowler.com/bliki/PublishedInterface.html） - Schwern

1个回答

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- kmdreko · Accepted Answer

在公共文档中展示私有项目似乎是错误的。这样的文档可能会引诱用户尝试使用它，即使有标志表明不应该如此。适合记录可能仍然对外部人员有用的箱内部内容的位置包括：

- 箱级别文档 - 模块级别文档（可以是虚拟模块，例如snafu::guide） - 存储库docs/文件夹（可见性较低，但是也是检查的另一个地方）

稍微不同的情况是记录正常用户不应使用但高级用户必须使用的项目。如果是这种情况，我建议在你的箱中添加一个“专家”功能标志，以指示这些项目应谨慎使用和理解。请参阅How to get a feature requirement tag in the documentation generated by `cargo doc`?。