使用yard的Rails控制器文档

Question

当我试图创建我的rails控制器和使用的参数的文档时，我遇到了困难，因为yard似乎期望参数作为方法参数存在。

# Renders a list of items
# @param params [Hash] the search parameters
# @option params [String] 'info' Only return items with this specific info
# @option params [Integer] 'limit' Only return <limit> items
def index
  # ... do something smart here
end

因此，对于这个文档，yard将发出一个警告，并且不会创建文档：

[warn]: @param tag has unknown parameter name: params 
in file `app/controllers/items_controller.rb' near line 8

有没有办法使用yard来记录这些项目，或者我需要手动完成？

Answer 1

我不知道Rails有没有通过Yard记录动作参数的约定。如果有人知道得更多的话，我会非常乐意去了解它的。

Yard非常灵活。例如，您可以为项目使用define your own tags。添加一个专门用于记录控制器操作参数的标记。

首先，在Yard选项文件.yardopts中包含标记定义。这个文件是从项目的根目录中提取的：

--type-name-tag controller_action_param:"Controller Action Parameters"

在控制器操作中使用新标记，如下例所示：

# Renders a list of items
# @controller_action_param :info [String] Only return items with this specific info
# @controller_action_param :limit [Integer] Only return <limit> items
def index
  # ... do something smart here
end

您现在定义的约定是参数名称是用于访问params data的键-例如params:info。

定义一个最适合你的标记名和标题文本--这只是一个例子。