如何配置Yard工具获取Ruby项目中全部缺失文档（含参数、initialize）？

问题背景 #

我在多数C/C++、Python项目中使用doxygen，但它并不支持Ruby（Gemini AI曾声称支持）。尝试rdoc遇到问题后，我转而使用Ruby的Yard工具。我看重doxygen的核心原因是它能全面报告缺失的文档——这比生成的HTML文档更重要，毕竟多数人会直接读代码而非文档。

目前我使用--list-undoc参数，能获取缺失文档的文件及方法列表，但存在以下不足：

• 无法报告方法参数的缺失文档
• 无法报告initialize()方法的缺失文档
• 不确定是否会跳过私有方法的缺失文档

我的.yardopts关键配置如下：

--list-undoc
--no-cache
--protected
--private

--title 'my-title'
--readme README.md
--charset utf-8
--markup rdoc
--no-progress
--safe
--verbose

解决方案 #

针对你遇到的几个问题，可以通过调整Yard的配置和参数来实现更全面的缺失文档检测：

1. 报告方法参数的缺失文档 #

Yard默认不会单独检测参数的缺失文档，需要启用lint模式来实现这一点。在.yardopts中添加：

--lint

启用lint后，Yard会检查方法参数、返回值等是否有缺失的文档注释，输出对应的警告信息。

2. 报告initialize()方法的缺失文档 #

默认情况下，Yard会将initialize()视为特殊方法，--list-undoc不会主动检测它。要让Yard包含对initialize()的检测，需要在.yardopts中添加：

--undoc-include private

结合你已有的--private参数，就能让Yard把initialize()（即使是私有）纳入缺失文档的检测范围。

3. 确保私有方法的缺失文档被报告 #

你已经配置了--private参数，这个参数会让Yard在处理文档时包含私有方法，但--list-undoc默认可能不会主动列出私有方法的缺失文档。配合--undoc-include private参数，就能确保私有方法的缺失文档被检测并输出。

最终推荐的.yardopts配置调整 #

将以下参数添加到你的配置中：

--lint
--undoc-include private

调整后的完整关键配置示例：

--list-undoc
--lint
--undoc-include private
--no-cache
--protected
--private

--title 'my-title'
--readme README.md
--charset utf-8
--markup rdoc
--no-progress
--safe
--verbose

启用这些参数后，Yard会：

• 列出所有缺失文档的文件、方法（包括initialize()）
• 检测并报告方法参数的缺失文档
• 包含对私有方法的缺失文档检测

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