Ruby on rails 如何记录rails应用程序？

我刚刚开始编写rails应用程序的文档。我知道这实际上是由rdoc完成的，所以我遵循了一些关于语法等的rdoc指南，但当我试图描述模型的属性、验证和模型之间的关系时，我陷入了困境，主要是因为这些东西是ActiveRecord的一部分。因此，我想知道是否有一些关于如何记录rails应用程序的指南或良好实践，或者我是否缺少一些东西

---

我知道我可以将所有这些都放在类描述中，但我想知道是否有一种方法与声明本身更紧密地联系在一起（has_many，validate_presence_of，等等），那么属性呢

我个人更喜欢YARD-，因为它在记录IMHO方面做得更好。 我不知道是否有特定的Rails处理程序可用，但编写一个很容易- 一个很好的例子可能是属性处理程序——庭院宝石的一部分：

---

lib/yard/handlers/ruby/attribute_handler.rb

请记住，您的测试是文档的一部分（针对开发人员），特别是在使用Cucumber时，场景很容易阅读。如果您的方法非常简短，并且有一个测试方法具有描述性名称，例如“应设置用户名”，我发现我通常不需要对该方法进行评论

---

我不会记录Rails的验证或其他部分。作为一名Rails开发人员的一部分是理解这些是如何工作的，我认为这是一个公平的假设，您的代码的另一个维护者在阅读它的时候会知道验证，或者Rails内置的其他东西。按照同样的逻辑，如果您可以将框架的功能或快乐路径（不偏离太多）与[有文档记录的]第三方代码结合使用，将为您编写大量文档。

我认为这是一种非常简单的方法，我认为唯一的问题是，它看起来仍然有点年轻，学习曲线比我预期的要明显，但我认为它有很多潜力。我甚至开始想象一些很好的特性，比如用迁移的文档输入数据库，然后将文档输入到生成器中，这样你可以一箭双雕，应用程序文档和数据库文档。我喜欢这种方法，对于开发团队来说，我想这是可行的，但在某些情况下，您需要一个真正的文档，一个可能不会严格为开发人员使用的文档，而是由一个实际上并不关心测试的人使用的文档（并且不必如此）。另一方面，验证并不总是很容易解释，即使对于程序员来说，例如，在我的应用程序中，我对一些必须介于-180和180之间的数值属性进行了一些验证。这是因为此atribute表示纬度值，且该值只能在此范围内。这只是一个简单的验证，我有其他验证，包括关系和限制，更抽象，即使我再次阅读代码时，第一次也不清楚。