我刚刚开始记录一个 Rails 应用程序。我知道这实际上是由 rdoc 完成的，所以我遵循了一些关于语法等的 rdoc 指南，但是当我试图描述模型的属性、验证和模型之间的关系时，我被卡住了，主要是因为这些东西是 ActiveRecord 的一部分。所以我想知道是否有一些关于如何记录 Rails 应用程序的指南或良好实践，或者我是否遗漏了什么？
我知道我可以将所有这些都放在类描述中，但我想知道是否有一种与声明本身更紧密相关的方法（has_many、validates_presence_of 等）以及属性呢？
我个人更喜欢 YARD - http://yardoc.org，因为它在记录恕我直言方面做得更好。我不知道是否有特定的 Rails 处理程序可用，但编写一个很容易 - http://yardoc.org/guides/extending-yard/writing-handlers.html 一个很好的例子可能是属性处理程序 -庭院宝石的一部分：lib/yard/handlers/ruby/attribute_handler.rb
请记住，您的测试是文档的一部分（针对开发人员），尤其是在您使用 Cucumber 的场景易于阅读的情况下。如果您的方法非常简短，并且有一个具有描述性名称的测试方法，例如“应该设置用户名”，我发现我通常不需要对该方法发表评论。
我不会记录验证或 Rails 的其他部分。作为 Rails 开发人员的一部分是了解这些是如何工作的，我认为这是一个公平的假设，即您的代码的另一个维护者会知道验证或 Rails 内置的其他内容。按照同样的逻辑，如果您可以将框架的功能或快乐路径（偏差不大）与 [已记录的] 第三方代码一起使用，那么将为您编写很多文档。