DRYing yard parameters

别等时光非礼了梦想. 提交于 2019-12-05 08:02:23

As you already specify in the macro that it should be expanded for first parameter of method, than you don't need to specify it when expanding macro. Also it seems to be impossible to tell for which parameter to expand macro. Another thing is that you can skip [new] in this case and seems that it is better to use @!macro instead of @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

I believe you can accomplish what you're looking for using YARDs Reference Tags.

From the docs:

If a tag's data begins with (see OBJECT) it is considered a "reference tag". A reference tag literally copies the tag data by the given tag name from the specified OBJECT. For instance, a method may copy all @param tags from a given object using the reference tag syntax:

# @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

This works with yardoc 0.9.8 (probably any version):

# @!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

Note the missing exclamation mark ! when calling the macro with @macro. This is the correct yardoc syntax.

易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!