使用YARD的文档模型属性 [英] Document model attributes with YARD

问题描述

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

I'm using YARD to generate docs for my rails app with makrdown as the script parser. Most of the documentation features just work great right out of the box. However, I'd also like to document the model attributes to one, record the list of available attributes on a model and two, to describe their semantic meaning.

我wasn在YARD中找不到任何特别的支持，我基本上只留下了类注释中的属性。有没有办法记录动态生成的模型属性，使其在标准属性/方法的文档中出现？

I wasn't able to find any special support for this in YARD and I'm basically left with simply listing out the attributes in the class comments. Is there a way to document the dynamically generated model attributes so that they appear in the documentation like standard attributes/methods?

P.S。我使用annodate-models gem在类列表的顶部生成一个基本的模式转储，但这不是我想要的。

P.S. I've used the annodate-models gem to generate a basic schema dump at the top of the class listing but that's not really what I want.

推荐答案

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

After quite a while searching around, I punted and manually added the documentation for the attributes to the model files. This is certainly not ideal, but hopefully the model structure won't change a whole lot.

我为该项目创建了一个.yardopts文件，并使用了命令行选项创建两个新的标签来标记这些东西：

I created a .yardopts file for the project and used the yard command-line options to create two new tags for marking these up:

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

这些为我提供了标记属性的特定标签，协会;他们将在文档中的属性和协会标题下显示。我可以添加：

These provide me with specific tags for marking up the attributes and associations; they will show up grouped under the "Attributes" and "Associations" headings in the documentation. I can add this:

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

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

Maybe someone will write a plugin for YARD that will parse out the annotate-models output.

这篇关于使用YARD的文档模型属性的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！