如何记录Rails应用程序？

Question

我刚刚开始记录Rails应用程序。我知道这实际上是由RDOC完成的，因此我遵循了一些有关语法的RDOC指南，但是当我试图描述模型，验证和模型之间的关系的属性时，我被卡住了，主要是因为这些东西是Activerecord的一部分。因此，我想知道有关如何记录铁轨应用程序还是我缺少的东西是否有一些指南或良好的习惯？

我知道我可以将所有这些都放在类描述中，但是我想知道是否有一种与声明本身更紧密相关的方式（has_many，naderates_presence_of等），属性呢？

Answer 1

我个人更喜欢院子 - http://yardoc.org ，因为它在记录恕我直言方面做得更好。我不知道是否有一个特定的轨道处理程序，但是写一个很容易 - http://yardoc.org/guides/extering-yard/writinghandlers.html一个很好的例子可能是属性处理程序 - 院子宝石的一部分：lib/Yard/handlers/ruby/attribute_handler.rb

Answer 2

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

验证或铁轨的其他部分我不会记录。成为铁路开发人员的一部分是了解这些工作是如何工作的，我认为这是一个公平的假设，即您的代码的另一个维护者在道路上读取它将知道验证验证，或者在铁轨中内置的其他东西。通过同样的逻辑，如果您可以使用[已记录]第三方代码的框架或快乐路径的功能（偏差太多），则将为您编写大量文档。