ruby - 如何使用 rdoc 处理自述文件以显示 ruby​​ 脚本帮助/使用信息

Question

我想将我的使用文档保存在自述文件（duh）中，而不是脚本顶部的注释。如何让 RDoc::usage 从自述文件中提取使用信息而不是脚本注释？

Answer 1

RDoc 旨在解析源文件，查看注释及其位置，构建变量的交叉引用，并在完成后将其全部绑定到一个体面的输出中。因为 RDoc 旨在处理源文件，所以它可能不是您想要做的最佳选择。

相反，您可能想查看基于标签的Yard。我可以用正确的格式将我的 README.textile 放入我的 RDoc 中吗？也为您提供了一些有用的信息。

在任何一种情况下，如果您无法让应用程序像您想要的那样解析自述文件类型的文档，您可以通过将所有文档以及类和方法存根放在文件中来欺骗它，以便解析器可以抓取他们需要创建可用文档的参数、全局变量和其他“whatnot”。

否则，您可能不得不放弃使用自动帮助并全部输入。

我的建议是使用 RDoc 方式，并在代码中记录。一点都不难做，输出也可以很满意。RDoc 能做的这么好的工作真是太神奇了。

Answer 2

我当然没有足够的经验告诉你答案，但请允许我一条建议。

大多数开发人员不太可能更新文档，即使它是实现之上的 3 行代码。

帮个忙，不要让这个过程变得更加困难。

将一般文档分开是一个好主意，但无论如何它与您的 RDoc 生成的输出无关。