ruby - 我如何记录提供 block 是可选的方法？

Question

我有一个这样记录的函数:

##
# Searches for street names in the local address database. Returns a list
# of strings, or invokes the block for each result.
#
# @param [String, Hash] query
#
#   Can be:
#
#   - A search string with optinal wildcards. Examples:
#     - "Bærumsv*"
#     - "Fornebuve_en"
#
# @param [Integer] limit
#
#   Limits the amount of results. See {#search_street_addresses} for usage
#   examples.
#
# @return [Array<String>]
#
#   A sorted array of street names.
#
# @yield [street_name] Invokes the block with a street name for each
#   result.
#

产生这个结果:

我的问题是文档说该函数需要一个 block 并返回一个值。实际上， block 是可选的。如果提供了该 block ，则会为每个结果调用它并且该函数不返回任何内容 (nil)。如果未提供 block ，则结果以数组形式返回。

如何在文档中明确说明这一点？有推荐的方法吗？

Answer 1

使用@overload

##
# Searches for street names in the local address database. Returns a list
# of strings, or invokes the block for each result.
#@overload search_street_names(query, limit: nil)
#  @param [String, Hash] query
#
#    Can be:
#
#    - A search string with optinal wildcards. Examples:
#      - "Bærumsv*"
#      - "Fornebuve_en"
#
#  @param [Integer] limit
#
#    Limits the amount of results. See {#search_street_addresses} for usage
#    examples.
#
#  @return [Array<String>]
#
#    A sorted array of street names.
#
#@overload search_street_names(query, limit: nil)
#  @param [String, Hash] query
#
#    Can be:
#
#    - A search string with optinal wildcards. Examples:
#      - "Bærumsv*"
#      - "Fornebuve_en"
#
#  @param [Integer] limit
#
#    Limits the amount of results. See {#search_street_addresses} for usage
#    examples.
#
#  @yield [street_name] Invokes the block with a street name for each
#    result.
##

返回: