rubyrdocyard

YARD how to document a @param of Array<String> type which could also be a blank array?


The following is a snippet of a method that accepts an array of strings or a blank array([]):

# @param [Array<String>] bar
def foo(bar)
  if bar.empty?
    # Do this
  else
    # Do that
  end
end

I feel like this @param type is a bit misleading.

Is there a better way to document the blank array use case explicitly?


Solution

  • In your case if you know that the expected argument is an array of strings, then [Array<String>] is enough (IMO) for @param. What might change is the return value whether the argument is empty or not, for that you can do as it's mentioned in the docs:

    Describes the return value (and type or types) of a method. You can list multiple return tags for a method in the case where a method has distinct return cases. In this case, each case should begin with “if …”.

    For your example:

    # @param bar [Array<String>]
    # @return [TypeX] if bar is empty
    # @return [TypeY] if bar is not empty
    def foo(bar)
      ...
    end