From a7a47709a5daa86d7b2d131de3579c5e562553ba Mon Sep 17 00:00:00 2001
From: "Theodore R. Smith" <theodore@phpexperts.pro>
Date: Sat, 30 Mar 2019 07:54:49 -0500
Subject: [PATCH 1/2] Fixed the documentation.

This is needed in preparation for the PhpStorm stub (php-ds/ext-ds#128).
---
 src/Hashable.php                 | 2 +-
 src/Map.php                      | 8 +++++---
 src/Pair.php                     | 4 +++-
 src/PriorityQueue.php            | 2 +-
 src/Queue.php                    | 4 ++--
 src/Set.php                      | 2 +-
 src/Traits/Capacity.php          | 6 +++---
 src/Traits/GenericCollection.php | 8 +++++---
 src/Traits/GenericSequence.php   | 4 ++++
 src/Vector.php                   | 2 +-
 10 files changed, 26 insertions(+), 16 deletions(-)

diff --git a/src/Hashable.php b/src/Hashable.php
index d4b31fb..83e505a 100644
--- a/src/Hashable.php
+++ b/src/Hashable.php
@@ -26,7 +26,7 @@ function hash();
      * Determines if two objects should be considered equal. Both objects will
      * be instances of the same class but may not be the same instance.
      *
-     * @param $obj An instance of the same class to compare to.
+     * @param $obj self An instance of the same class to compare to.
      *
      * @return bool
      */
diff --git a/src/Map.php b/src/Map.php
index 6415579..3e482a4 100644
--- a/src/Map.php
+++ b/src/Map.php
@@ -393,6 +393,10 @@ public function reduce(callable $callback, $initial = null)
     /**
      * Completely removes a pair from the internal array by position. It is
      * important to remove it from the array and not just use 'unset'.
+     *
+     * @param int $position
+     *
+     * @return mixed
      */
     private function delete(int $position)
     {
@@ -434,9 +438,7 @@ public function remove($key, $default = null)
     }
 
     /**
-     * Returns a reversed copy of the map.
-     *
-     * @return Map
+     * Sorts the map into the reversed order.
      */
     public function reverse()
     {
diff --git a/src/Pair.php b/src/Pair.php
index 54e85f2..28c9cc9 100644
--- a/src/Pair.php
+++ b/src/Pair.php
@@ -88,8 +88,10 @@ public function jsonSerialize()
 
     /**
      * Returns a string representation of the pair.
+     *
+     * @return string a string representation of the pair.
      */
-    public function __toString()
+    public function __toString(): string
     {
         return 'object(' . get_class($this) . ')';
     }
diff --git a/src/PriorityQueue.php b/src/PriorityQueue.php
index ea16e2f..c94be9d 100644
--- a/src/PriorityQueue.php
+++ b/src/PriorityQueue.php
@@ -50,7 +50,7 @@ public function clear()
     /**
      * @inheritDoc
      */
-    public function copy(): \Ds\Collection
+    public function copy(): Collection
     {
         $copy = new PriorityQueue();
 
diff --git a/src/Queue.php b/src/Queue.php
index c9433cf..18736cb 100644
--- a/src/Queue.php
+++ b/src/Queue.php
@@ -65,7 +65,7 @@ public function clear()
     /**
      * @inheritDoc
      */
-    public function copy(): \Ds\Collection
+    public function copy(): Collection
     {
         return new self($this->deque);
     }
@@ -81,7 +81,7 @@ public function count(): int
     /**
      * Returns the value at the front of the queue without removing it.
      *
-     * @return
+     * @return mixed
      */
     public function peek()
     {
diff --git a/src/Set.php b/src/Set.php
index 83eb735..22322b8 100644
--- a/src/Set.php
+++ b/src/Set.php
@@ -101,7 +101,7 @@ public function contains(...$values): bool
     /**
      * @inheritDoc
      */
-    public function copy(): \Ds\Collection
+    public function copy(): Collection
     {
         return new self($this);
     }
diff --git a/src/Traits/Capacity.php b/src/Traits/Capacity.php
index 2111c0c..1d381f3 100644
--- a/src/Traits/Capacity.php
+++ b/src/Traits/Capacity.php
@@ -37,7 +37,7 @@ public function allocate(int $capacity)
     }
 
     /**
-     * @return the structures growth factor.
+     * @return float the structures growth factor.
      */
     protected function getGrowthFactor(): float
     {
@@ -92,7 +92,7 @@ protected function decreaseCapacity()
     }
 
     /**
-     * @return whether capacity should be increased.
+     * @return bool whether capacity should be increased.
      */
     protected function shouldDecreaseCapacity(): bool
     {
@@ -100,7 +100,7 @@ protected function shouldDecreaseCapacity(): bool
     }
 
     /**
-     * @return whether capacity should be increased.
+     * @return bool whether capacity should be increased.
      */
     protected function shouldIncreaseCapacity(): bool
     {
diff --git a/src/Traits/GenericCollection.php b/src/Traits/GenericCollection.php
index fa9641d..ea353de 100644
--- a/src/Traits/GenericCollection.php
+++ b/src/Traits/GenericCollection.php
@@ -25,7 +25,7 @@ public function isEmpty(): bool
      * Returns a representation that can be natively converted to JSON, which is
      * called when invoking json_encode.
      *
-     * @return mixed
+     * @return mixed the data to be JSON encoded.
      *
      * @see JsonSerializable
      */
@@ -60,7 +60,7 @@ abstract public function toArray(): array;
      *
      * @return array
      */
-    public function __debugInfo()
+    public function __debugInfo(): array
     {
         return $this->toArray();
     }
@@ -68,8 +68,10 @@ public function __debugInfo()
     /**
      * Returns a string representation of the collection, which is invoked when
      * the collection is converted to a string.
+     *
+     * @return string
      */
-    public function __toString()
+    public function __toString(): string
     {
         return 'object(' . get_class($this) . ')';
     }
diff --git a/src/Traits/GenericSequence.php b/src/Traits/GenericSequence.php
index 61e3aa5..63152f5 100644
--- a/src/Traits/GenericSequence.php
+++ b/src/Traits/GenericSequence.php
@@ -236,6 +236,10 @@ public function reversed(): Sequence
     /**
      * Converts negative or large rotations into the minimum positive number
      * of rotations required to rotate the sequence by a given $r.
+     *
+     * @param int $r
+     *
+     * @return int
      */
     private function normalizeRotations(int $r)
     {
diff --git a/src/Vector.php b/src/Vector.php
index 5a2ba1d..054f717 100644
--- a/src/Vector.php
+++ b/src/Vector.php
@@ -23,7 +23,7 @@ protected function getGrowthFactor(): float
     }
 
     /**
-     * @return whether capacity should be increased.
+     * @return bool whether capacity should be increased.
      */
     protected function shouldIncreaseCapacity(): bool
     {

From d05e0991a100e32177ba3ed62438aae7f69b99e0 Mon Sep 17 00:00:00 2001
From: "Theodore R. Smith" <theodore@phpexperts.pro>
Date: Sat, 30 Mar 2019 08:14:19 -0500
Subject: [PATCH 2/2] Made the interfaces conform to PHP standards.

1. "All methods and properties of classes and interfaces must specify their
   visibility: public, protected or private.", from the PSR-12 draft.
2. It is required by convention for inclusion as a PhpStorm stub
   (see php-ds/ext-ds#128).
---
 src/Collection.php | 10 ++++-----
 src/Hashable.php   |  4 ++--
 src/Sequence.php   | 54 +++++++++++++++++++++++-----------------------
 3 files changed, 34 insertions(+), 34 deletions(-)

diff --git a/src/Collection.php b/src/Collection.php
index 9f3acd2..65baabb 100644
--- a/src/Collection.php
+++ b/src/Collection.php
@@ -13,21 +13,21 @@ interface Collection extends \Traversable, \Countable, \JsonSerializable
     /**
      * Removes all values from the collection.
      */
-    function clear();
+    public function clear();
 
     /**
      * Returns the size of the collection.
      *
      * @return int
      */
-    function count(): int;
+    public function count(): int;
 
     /**
      * Returns a shallow copy of the collection.
      *
      * @return Collection a copy of the collection.
      */
-    function copy(): Collection;
+    public function copy(): Collection;
 
     /**
      * Returns whether the collection is empty.
@@ -37,7 +37,7 @@ function copy(): Collection;
      *
      * @return bool
      */
-    function isEmpty(): bool;
+    public function isEmpty(): bool;
 
     /**
      * Returns an array representation of the collection.
@@ -48,5 +48,5 @@ function isEmpty(): bool;
      *
      * @return array
      */
-    function toArray(): array;
+    public function toArray(): array;
 }
diff --git a/src/Hashable.php b/src/Hashable.php
index 83e505a..af00753 100644
--- a/src/Hashable.php
+++ b/src/Hashable.php
@@ -20,7 +20,7 @@ interface Hashable
      *
      * @return mixed
      */
-    function hash();
+    public function hash();
 
     /**
      * Determines if two objects should be considered equal. Both objects will
@@ -30,5 +30,5 @@ function hash();
      *
      * @return bool
      */
-    function equals($obj): bool;
+    public function equals($obj): bool;
 }
diff --git a/src/Sequence.php b/src/Sequence.php
index 414e84f..8254e84 100644
--- a/src/Sequence.php
+++ b/src/Sequence.php
@@ -20,7 +20,7 @@ interface Sequence extends Collection
      *                      allocated. Capacity will stay the same if this value
      *                      is less than or equal to the current capacity.
      */
-    function allocate(int $capacity);
+    public function allocate(int $capacity);
 
     /**
      * Updates every value in the sequence by applying a callback, using the
@@ -28,14 +28,14 @@ function allocate(int $capacity);
      *
      * @param callable $callback Accepts the value, returns the new value.
      */
-    function apply(callable $callback);
+    public function apply(callable $callback);
 
     /**
      * Returns the current capacity of the sequence.
      *
      * @return int
      */
-    function capacity(): int;
+    public function capacity(): int;
 
     /**
      * Determines whether the sequence contains all of zero or more values.
@@ -45,7 +45,7 @@ function capacity(): int;
      * @return bool true if at least one value was provided and the sequence
      *              contains all given values, false otherwise.
      */
-    function contains(...$values): bool;
+    public function contains(...$values): bool;
 
     /**
      * Returns a new sequence containing only the values for which a callback
@@ -57,7 +57,7 @@ function contains(...$values): bool;
      *
      * @return Sequence
      */
-    function filter(callable $callback = null): Sequence;
+    public function filter(callable $callback = null): Sequence;
 
     /**
      * Returns the index of a given value, or false if it could not be found.
@@ -66,7 +66,7 @@ function filter(callable $callback = null): Sequence;
      *
      * @return int|bool
      */
-    function find($value);
+    public function find($value);
 
     /**
      * Returns the first value in the sequence.
@@ -75,7 +75,7 @@ function find($value);
      *
      * @throws \UnderflowException if the sequence is empty.
      */
-    function first();
+    public function first();
 
     /**
      * Returns the value at a given index (position) in the sequence.
@@ -86,7 +86,7 @@ function first();
      *
      * @throws \OutOfRangeException if the index is not in the range [0, size-1]
      */
-    function get(int $index);
+    public function get(int $index);
 
     /**
      * Inserts zero or more values at a given index.
@@ -99,7 +99,7 @@ function get(int $index);
      *
      * @throws \OutOfRangeException if the index is not in the range [0, n]
      */
-    function insert(int $index, ...$values);
+    public function insert(int $index, ...$values);
 
     /**
      * Joins all values of the sequence into a string, adding an optional 'glue'
@@ -109,7 +109,7 @@ function insert(int $index, ...$values);
      *
      * @return string
      */
-    function join(string $glue = null): string;
+    public function join(string $glue = null): string;
 
     /**
      * Returns the last value in the sequence.
@@ -118,7 +118,7 @@ function join(string $glue = null): string;
      *
      * @throws \UnderflowException if the sequence is empty.
      */
-    function last();
+    public function last();
 
     /**
      * Returns a new sequence using the results of applying a callback to each
@@ -128,7 +128,7 @@ function last();
      *
      * @return Sequence
      */
-    function map(callable $callback): Sequence;
+    public function map(callable $callback): Sequence;
 
     /**
      * Returns the result of adding all given values to the sequence.
@@ -137,7 +137,7 @@ function map(callable $callback): Sequence;
      *
      * @return Sequence
      */
-    function merge($values): Sequence;
+    public function merge($values): Sequence;
 
     /**
      * Removes the last value in the sequence, and returns it.
@@ -146,14 +146,14 @@ function merge($values): Sequence;
      *
      * @throws \UnderflowException if the sequence is empty.
      */
-    function pop();
+    public function pop();
 
     /**
      * Adds zero or more values to the end of the sequence.
      *
      * @param mixed ...$values
      */
-    function push(...$values);
+    public function push(...$values);
 
     /**
      * Iteratively reduces the sequence to a single value using a callback.
@@ -166,7 +166,7 @@ function push(...$values);
      * @return mixed The carry value of the final iteration, or the initial
      *               value if the sequence was empty.
      */
-    function reduce(callable $callback, $initial = null);
+    public function reduce(callable $callback, $initial = null);
 
     /**
      * Removes and returns the value at a given index in the sequence.
@@ -177,19 +177,19 @@ function reduce(callable $callback, $initial = null);
      *
      * @throws \OutOfRangeException if the index is not in the range [0, size-1]
      */
-    function remove(int $index);
+    public function remove(int $index);
 
     /**
      * Reverses the sequence in-place.
      */
-    function reverse();
+    public function reverse();
 
     /**
      * Returns a reversed copy of the sequence.
      *
      * @return Sequence
      */
-    function reversed();
+    public function reversed();
 
     /**
      * Rotates the sequence by a given number of rotations, which is equivalent
@@ -198,7 +198,7 @@ function reversed();
      *
      * @param int $rotations The number of rotations (can be negative).
      */
-    function rotate(int $rotations);
+    public function rotate(int $rotations);
 
     /**
      * Replaces the value at a given index in the sequence with a new value.
@@ -208,7 +208,7 @@ function rotate(int $rotations);
      *
      * @throws \OutOfRangeException if the index is not in the range [0, size-1]
      */
-    function set(int $index, $value);
+    public function set(int $index, $value);
 
     /**
      * Removes and returns the first value in the sequence.
@@ -217,7 +217,7 @@ function set(int $index, $value);
      *
      * @throws \UnderflowException if the sequence was empty.
      */
-    function shift();
+    public function shift();
 
     /**
      * Returns a sub-sequence of a given length starting at a specified index.
@@ -240,7 +240,7 @@ function shift();
      *
      * @return Sequence
      */
-    function slice(int $index, int $length = null): Sequence;
+    public function slice(int $index, int $length = null): Sequence;
 
     /**
      * Sorts the sequence in-place, based on an optional callable comparator.
@@ -248,7 +248,7 @@ function slice(int $index, int $length = null): Sequence;
      * @param callable|null $comparator Accepts two values to be compared.
      *                                  Should return the result of a <=> b.
      */
-    function sort(callable $comparator = null);
+    public function sort(callable $comparator = null);
 
     /**
      * Returns a sorted copy of the sequence, based on an optional callable
@@ -259,19 +259,19 @@ function sort(callable $comparator = null);
      *
      * @return Sequence
      */
-    function sorted(callable $comparator = null): Sequence;
+    public function sorted(callable $comparator = null): Sequence;
 
     /**
      * Returns the sum of all values in the sequence.
      *
      * @return int|float The sum of all the values in the sequence.
      */
-    function sum();
+    public function sum();
 
     /**
      * Adds zero or more values to the front of the sequence.
      *
      * @param mixed ...$values
      */
-    function unshift(...$values);
+    public function unshift(...$values);
 }