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

戻り値：