Documenting zip() and zipWith()

src/Collection/CollectionInterface.php

@@ -819,7 +819,7 @@ interface CollectionInterface extends Iterator, JsonSerializable
      * ### Example:
      *
      * ```
-     * $items [1, 2, 3];
+     * $items = [1, 2, 3];
      * $decorated = (new Collection($items))->through(function ($collection) {
      *      return new MyCustomCollection($collection);
      * });
@@ -832,6 +832,44 @@ interface CollectionInterface extends Iterator, JsonSerializable
     public function through(callable $handler);
 
     /**
+     * Combines the elements of this collection with each of the elements of the
+     * passed iterables, using their positional index as a reference.
+     *
+     * ### Example:
+     *
+     * ```
+     * $collection = new Collection([1, 2]);
+     * $collection->zip([3, 4], [5, 6])->toList(); // returns [[1, 3, 5], [2, 4, 6]]
+     * ```
+     *
+     * @param array|\Traversable ...$items The collections to zip.
+     * @return \Cake\Collection\CollectionInterface
+     */
+    public function zip($items);
+
+    /**
+     * Combines the elements of this collection with each of the elements of the
+     * passed iterables, using their positional index as a reference.
+     *
+     * The resulting element will be the return value of the $callable function.
+     *
+     * ### Example:
+     *
+     * ```
+     * $collection = new Collection([1, 2]);
+     * $zipped = $collection->zip([3, 4], [5, 6], function () {
+     *   return array_sum(func_get_args());
+     * });
+     * $zipped->toList(); // returns [9, 12]; [(1 + 3 + 5), (2 + 4 + 6)]
+     * ```
+     *
+     * @param array|\Traversable ...$items The collections to zip.
+     * @param callable $callable The function to use for zipping the elements together.
+     * @return \Cake\Collection\CollectionInterface
+     */
+    public function zipWith($items, $callable);
+
+    /**
      * Returns whether or not there are elements in this collection
      *
      * ### Example:
@@ -840,6 +878,7 @@ interface CollectionInterface extends Iterator, JsonSerializable
      * $items [1, 2, 3];
      * (new Collection($items))->isEmpty(); // false
      * ```
+     *
      * ```
      * (new Collection([]))->isEmpty(); // true
      * ```