ruby - 烘干场参数

Question

我已经得到了我认为是相当基本的 yard 宏用法，其中我有一个 Hash 结构，其中包含多个在多个函数之间共享的选项。我希望使用宏只是为了防止我不得不在整个地方复制这个结构，但它似乎不像那样工作。

我期望的工作是：

# @macro [new] my_hash
#   @param  $1 [Hash,Array<Hash>] Inputted my_hash
#   @option $1 [String] :a Value for A.
#   @option $1 [String] :b Value for B.
#   @option $1 [String] :c Value for C.

##
# my_func does stuff
# @macro my_hash h1
def my_func h1
end

## 
# other_func does stuff
# @macro my_hash h2
def other_func h2, a, b
end

并正确记录 h1 和 h2。我想我已经发现至少 $1 不能像那样工作，而是从函数本身获取，但我可以调用这两个参数 h1 并在宏中用 h1 替换 $1 ，但我仍然没有得到我想要的.

http://rubydoc.info/docs/yard/file/docs/Tags.md#macro上的“定义简单宏”示例表明我可以做到这一点（请注意，我找到了带有 @!macro 的示例，有些没有但似乎都不起作用）。

我对院子不太了解，但这不起作用吗？我可以做一些类似的事情来实现我的结果吗？是否有调试功能可以解释这一点，因为庭院服务器控制台中没有出现错误？

谢谢

Answer 1

正如您已经在宏中指定应该为方法的第一个参数扩展它，而不是在扩展宏时不需要指定它。此外，似乎无法确定扩展宏的参数。另一件事是您可以[new]在这种情况下跳过，似乎最好使用@!macro而不是@macro.

# @!macro my_hash
#   @param  $1 [Hash,Array<Hash>] Inputted my_hash
#   @option $1 [String] :a Value for A.
#   @option $1 [String] :b Value for B.
#   @option $1 [String] :c Value for C.

##
# my_func does stuff
# @!macro my_hash
def my_func h1
end

##
# other_func does stuff
# @!macro my_hash
def other_func h2, a, b
end

Answer 2

我相信您可以使用 YARDs Reference Tags完成您正在寻找的东西。

从文档：

如果标签的数据以(see OBJECT)它开头，则被视为“参考标签”。引用标签从指定的 OBJECT 按给定的标签名称逐字复制标签数据。例如，一个方法可以使用引用标记语法从给定对象复制所有@param 标记：

# @param [String] user the username for the operation
# @param [String] host the host that this user is associated with
# @param [Time] time the time that this operation took place
def clean(user, host, time = Time.now) end

# @param (see #clean)
def activate(user, host, time = Time.now) end

Answer 3

这适用于 yardoc 0.9.8（可能是任何版本）：

# @!macro my_hash
#   @param  $1 [Hash,Array<Hash>] Inputted my_hash
#   @option $1 [String] :a Value for A.
#   @option $1 [String] :b Value for B.
#   @option $1 [String] :c Value for C.

##
# my_func does stuff
# @macro my_hash
def my_func h1
end

##
# other_func does stuff
# @macro my_hash
def other_func h2, a, b
end

注意缺少的感叹号！使用 调用宏时@macro。这是正确的yardoc 语法。