Added some missing documentation and trait refactor

Author: rtheunissen

src/Collection.php

@@ -2,7 +2,9 @@
 namespace Ds;
 
 /**
- * Collection Interface
+ * Collection is the base interface which covers functionality common to all the
+ * data structures in this library. It guarantees that all structures are
+ * traversable, countable, and can be converted to json using json_encode().
  *
  * @package Ds
  */
@@ -23,7 +25,7 @@ function count(): int;
     /**
      * Returns a shallow copy of the collection.
      *
-     * @return \Ds\Collection a copy of the collection.
+     * @return Collection a copy of the collection.
      */
     function copy(): Collection;
 

src/Deque.php

@@ -2,14 +2,19 @@
 namespace Ds;
 
 /**
- * Deque
+ * A Deque (pronounced "deck") is a sequence of values in a contiguous buffer
+ * that grows and shrinks automatically. The name is a common abbreviation of
+ * "double-ended queue".
+ *
+ * While a Deque is very similar to a Vector, it offers constant time operations
+ * at both ends of the buffer, ie. shift, unshift, push and pop are all O(1).
  *
  * @package Ds
  */
 final class Deque implements \IteratorAggregate, \ArrayAccess, Sequence
 {
-    use Traits\Collection;
-    use Traits\Sequence;
+    use Traits\GenericCollection;
+    use Traits\GenericSequence;
     use Traits\SquaredCapacity;
 
     const MIN_CAPACITY = 8;

src/Hashable.php

@@ -2,25 +2,33 @@
 namespace Ds;
 
 /**
- * Hashable Interface
+ * Hashable is an interface which allows objects to be used as keys.
+ *
+ * It’s an alternative to spl_object_hash(), which determines an object’s hash
+ * based on its handle: this means that two objects that are considered equal
+ * by an implicit definition would not treated as equal because they are not
+ * the same instance.
  *
  * @package Ds
  */
 interface Hashable
 {
     /**
-     * Produces a scalar value to be used as the object's hash.
+     * Produces a scalar value to be used as the object's hash, which determines
+     * where it goes in the hash table. While this value does not have to be
+     * unique, objects which are equal must have the same hash value.
      *
-     * @return mixed Scalar hash value.
+     * @return mixed
      */
     function hash();
 
     /**
-     * Returns whether this object is considered equal to another.
+     * 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
+     * @param $obj An instance of the same class to compare to.
      *
-     * @return bool true if equal, false otherwise.
+     * @return bool
      */
     function equals($obj): bool;
 }