使用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

因此，对于此文档场将发出警告并且不会创建文档：

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

有没有办法使用yard来记录这些类型的项目，或者我需要手动执行此操作？

Answer 1

我不知道 Rails 约定通过 Yard 记录操作参数。如果有人知道更多的话，我会非常乐意了解其中一个。

院子非常灵活。例如，您可以为项目定义自己的标签。添加专用于记录控制器操作参数的标签。

首先将标签定义包含在 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[:info]。

定义最适合您的标签名称和标题文本 - 这只是一个示例。