Question

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

def get_endpoint(params: {})
end

我希望此方法的调用者能够传递一些可选参数。

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

然而，YARD自己的文档说：

注意：对于关键字参数，请使用@param，而不是@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