使用YARD记录模型属性

Question

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

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

PS我已经使用annodate-models gem在类列表的顶部生成一个基本的模式转储,但这不是我想要的.

Answer 1

@!attribute为此目的,YARD现在似乎有自己的(注意感叹号)标签:

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