How do I document methods where providing a block is optional?

Question

I have a function documented like this:

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

Yielding this result:

My issue is that the documentation says that the function expects a block and that it returns a value. In reality, the block is optional. If the block is provided, it is invoked for each result and the function returns nothing (nil). If no block is provided, the results are returned in an Array.

How do I make this clear in the documentation? Is there a recommended way?

Answer 1

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

Returns: