使用 YARD 记录模型属性

Question

我正在使用 YARD 为我的 Rails 应用程序生成文档，并使用 makrdown 作为脚本解析器。大多数文档功能开箱即用，效果很好。但是，我还想将模型属性记录为一个，记录模型上的可用属性列表，以及两个，以描述它们的语义含义。

我在 YARD 中找不到对此的任何特殊支持，我基本上只能在类注释中简单地列出属性。有没有一种方法可以记录动态生成的模型属性，以便它们像标准属性/方法一样出现在文档中？

PS 我已经使用 annodate-models gem 在类列表的顶部生成基本模式转储，但这并不是我真正想要的。

Answer 1

看来 YARD 现在有自己的 @!attribute （注意感叹号）用于此目的标签：

http://rubydoc.info/docs/yard/file/docs/Tags.md#attribute

示例：

class Task < ActiveRecord::Base
  # @!attribute name
  #   @return [String] The name of the task.

  # @!attribute description
  #   @return [String] The description of the task.

  # @!attribute active
  #   @return [Boolean] Marks whether the task is active or not.
end

这将生成很好的属性文档。唯一需要注意的是，您始终保持文档最新，因为当您从数据库等中删除属性时，没有人会检查您是否从文档中删除属性。

Answer 2

经过一段时间的搜索后，我手动将属性文档添加到模型文件中。这当然不理想，但希望模型结构不会发生太大变化。

我为该项目创建了一个 .yardopts 文件，并使用yard命令行选项创建了两个新标签来标记它们：

--type-name-tag 'attribute:Attributes' --type-name-tag 'association:Associations'

这些标签为我提供了用于标记属性和关联的特定标签；它们将显示在文档中的“属性”和“关联”标题下。我可以添加这一点：

# @attribute name [String] The name of the object
# @association relatedObjs [Array<AnotherClass>] Objects needed to perform a certain function

也许有人会为 YARD 编写一个插件来解析注释模型输出。