我正在使用YARD为我的 rails 应用程序生成文档,并将 makrdown 作为脚本解析器。大多数文档功能开箱即用。但是,我还想将模型属性记录为一个,记录模型上的可用属性列表和两个,以描述它们的语义含义。
我无法在 YARD 中找到对此的任何特殊支持,我基本上只需要在类注释中列出属性即可。有没有办法记录动态生成的模型属性,以便它们像标准属性/方法一样出现在文档中?
PS 我已经使用 annodate-models gem 在类列表的顶部生成基本模式转储,但这并不是我真正想要的。
我正在使用YARD为我的 rails 应用程序生成文档,并将 makrdown 作为脚本解析器。大多数文档功能开箱即用。但是,我还想将模型属性记录为一个,记录模型上的可用属性列表和两个,以描述它们的语义含义。
我无法在 YARD 中找到对此的任何特殊支持,我基本上只需要在类注释中列出属性即可。有没有办法记录动态生成的模型属性,以便它们像标准属性/方法一样出现在文档中?
PS 我已经使用 annodate-models gem 在类列表的顶部生成基本模式转储,但这并不是我真正想要的。
似乎 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
这将为您的属性提供很好的文档。唯一需要注意的是,您始终保持文档是最新的,因为当您从数据库中删除某个属性等时,没有人会检查您是否从文档中删除了该属性。
经过一段时间的搜索,我将属性文档手动添加到模型文件中。这当然不理想,但希望模型结构不会发生太大变化。
我为项目创建了一个 .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 输出。