ruby - YARD 用于具有默认哈希值的关键字参数

Question

我有一个看起来像这样的方法:

def get_endpoint(params: {})
end

我希望这个方法的调用者能够传入一些可选参数。

我想编写 YARD 文档来支持这一点，如果我不使用关键字参数，我会使用 @option 声明。

但是，YARD 自己的文档说:

Note: For keyword parameters, use @param, not @option.

所以我尝试了:

  # @param params [Hash] options to be used in request
  # @param date [String] date in YYYYMMDD
  # @param start_time [Integer] start_time in Epoch

失败是因为 YARD 只看到我正在使用的 params 关键字参数。确切的失败是:

@param tag has unknown parameter name: date

然后我尝试使用 @option 语法替换为 param 关键字:

  # @param params [Hash] options to be used in request
  # @param params [String] :date in YYYYMMDD
  # @param params [Integer] :start_time in Epoch

这会导致不同的错误:

@param tag has duplicate parameter name: params

理想情况下，我想用此方法的用户可以使用的 3 或 4 个选项来描述 params 哈希。有办法做到这一点吗？

Answer 1

该签名不为 :date 或 :start_time 使用关键字参数。这些参数的关键字参数将指定为类似以下内容:

def get_endpoint(date:, start_time:)

@option 专门用于指定将包含在选项 Hash 中的选项，在您的情况下 params。由于您正在为 params 使用关键字参数，因此我建议为此添加 @param 标记以清楚地标识关键字参数。例如:

@param params [Hash]  options to be used in request
@option params [String] :date in YYYYMMDD
@option params [Integer] :start_time in Epoch

Documentation for @options以防万一。