使用 YARD 记录模型属性

Question

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

我无法在 YARD 中找到任何对此的特殊支持，我基本上只需要列出类 cmets 中的属性。有没有办法记录动态生成的模型属性，以便它们像标准属性/方法一样出现在文档中？

附：我已经使用 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 编写一个插件来解析 annotate-models 输出。