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

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

产生这个结果：

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

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

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

回报：