Documentation: Add API docs for Array sorting methods (crystal-lang#5637

)

* Documentation: Add API docs for Array sorting methods
- Array#sort(&block : T, T -> Int32)
- Array#sort!(&block : T, T -> Int32)
- Array#sort_by(&block : T -> _)
- Array#sort_by!(&block : T -> _)

* Documentation: Add API docs for Array#swap

* Documentation: Update based on code review
- Add explicit return types for sorting methods
- Update descriptions based on code review
- Format code using crystal's format tool

* Documentation: Remove comments about optional blocks from Array#sort! and Array#sort

* Documentation: Update descriptions for Array sorting methods

src/array.cr

@@ -1535,57 +1535,110 @@ class Array(T)
     self
   end
 
-  # Returns an array with all elements in the collection sorted.
+  # Returns a new array with all elements sorted based on the return value of
+  # their comparison method `#<=>`
   #
   # ```
   # a = [3, 1, 2]
   # a.sort # => [1, 2, 3]
   # a      # => [3, 1, 2]
   # ```
-  #
-  # Optionally, a block may be given that must implement a comparison, either with the comparison operator `<=>`
-  # or a comparison between *a* and *b*, where a < b yields -1, a == b yields 0, and a > b yields 1.
-  def sort
+  def sort : Array(T)
     dup.sort!
   end
 
-  def sort(&block : T, T -> Int32)
+  # Returns a new array with all elements sorted based on the comparator in the
+  # given block.
+  #
+  # The block must implement a comparison between two elements *a* and *b*,
+  # where `a < b` returns `-1`, `a == b` returns `0`, and `a > b` returns `1`.
+  # The comparison operator `<=>` can be used for this.
+  #
+  # ```
+  # a = [3, 1, 2]
+  # b = a.sort { |a, b| b <=> a }
+  #
+  # b # => [3, 2, 1]
+  # a # => [3, 1, 2]
+  # ```
+  def sort(&block : T, T -> Int32) : Array(T)
     dup.sort! &block
   end
 
-  # Modifies `self` by sorting the elements in the collection.
+  # Modifies `self` by sorting all elements based on the return value of their
+  # comparison method `#<=>`
   #
   # ```
   # a = [3, 1, 2]
   # a.sort!
   # a # => [1, 2, 3]
   # ```
-  #
-  # Optionally, a block may be given that must implement a comparison, either with the comparison operator `<=>`
-  # or a comparison between *a* and *b*, where a < b yields -1, a == b yields 0, and a > b yields 1.
-  def sort!
+  def sort! : Array(T)
     Array.intro_sort!(@buffer, @size)
     self
   end
 
-  def sort!(&block : T, T -> Int32)
+  # Modifies `self` by sorting all elements based on the comparator in the given
+  # block.
+  #
+  # The given block must implement a comparison between two elements
+  # *a* and *b*, where `a < b` returns `-1`, `a == b` returns `0`,
+  # and `a > b` returns `1`.
+  # The comparison operator `<=>` can be used for this.
+  #
+  # ```
+  # a = [3, 1, 2]
+  # a.sort! { |a, b| b <=> a }
+  # a # => [3, 2, 1]
+  # ```
+  def sort!(&block : T, T -> Int32) : Array(T)
     Array.intro_sort!(@buffer, @size, block)
     self
   end
 
-  def sort_by(&block : T -> _)
+  # Returns a new array with all elements sorted. The given block is called for
+  # each element, then the comparison method #<=> is called on the object
+  # returned from the block to determine sort order.
+  #
+  # ```
+  # a = %w(apple pear fig)
+  # b = a.sort_by { |word| word.size }
+  # b # => ["fig", "pear", "apple"]
+  # a # => ["apple", "pear", "fig"]
+  # ```
+  def sort_by(&block : T -> _) : Array(T)
     dup.sort_by! { |e| yield(e) }
   end
 
-  def sort_by!(&block : T -> _)
+  # Modifies `self` by sorting all elements. The given block is called for
+  # each element, then the comparison method #<=> is called on the object
+  # returned from the block to determine sort order.
+  #
+  # ```
+  # a = %w(apple pear fig)
+  # a.sort_by! { |word| word.size }
+  # a # => ["fig", "pear", "apple"]
+  # ```
+  def sort_by!(&block : T -> _) : Array(T)
     sorted = map { |e| {e, yield(e)} }.sort! { |x, y| x[1] <=> y[1] }
     @size.times do |i|
       @buffer[i] = sorted.to_unsafe[i][0]
     end
     self
   end
 
-  def swap(index0, index1)
+  # Swaps the elements at *index0* and *index1* and returns `self`.
+  # Raises an `IndexError` if either index is out of bounds.
+  #
+  # ```
+  # a = ["first", "second", "third"]
+  # a.swap(1, 2)  # => ["first", "third", "second"]
+  # a             # => ["first", "third", "second"]
+  # a.swap(0, -1) # => ["second", "third", "first"]
+  # a             # => ["second", "third", "first"]
+  # a.swap(2, 3)  # => raises "Index out of bounds (IndexError)"
+  # ```
+  def swap(index0, index1) : Array(T)
     index0 += size if index0 < 0
     index1 += size if index1 < 0