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

user_74089 0
Viewed 601

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?

yard rdoc ruby
2 Answers

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
user_50251160

Accepting an array of arbitrary length obviously implies accepting an array of length zero. This is so obvious, it doesn't need to be documented.

Now, if the method does something totally different and unexpected when passed an empty array, this behavior could be documented in a separate overload (which seems to be partially supported by RubyMine).

Although, if the method does two completely different things depending on its arguments, one might ask the question why those aren't two different methods in the first place.

user_29880
Related