Question

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

我无法在YARD中找到任何特殊的支持，我基本上只是列出了类评论中的属性。有没有办法记录动态生成的模型属性，以便它们出现在文档中，如标准属性/方法？

P.S。我已经使用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文件，并使用院子命令行选项创建了两个新标记来标记这些：

--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编写一个插件来解析注释模型的输出。

使用YARD记录模型属性

2 个答案: