Code coverage, docs, test updates

Author: rtheunissen

.gitattributes

@@ -0,0 +1,5 @@
+/.gitattributes     export-ignore
+/.gitignore         export-ignore
+/.travis.yml        export-ignore
+/.scrutinizer.yml   export-ignore
+/phpunit.xml        export-ignore

.gitignore

@@ -1,2 +1,3 @@
+build
 vendor
 composer.lock

.scrutinizer.yml

@@ -0,0 +1,18 @@
+build:
+    tests:
+        override:
+            -
+                command: 'phpunit'
+                coverage:
+                    file: 'build/logs/coverage.xml'
+                    format: 'php-clover'
+
+checks:
+    php:
+        line_length:
+            max_length: '80'
+
+tools:
+    php_code_sniffer:
+        config:
+            standard: "PSR2"

.travis.yml

@@ -6,10 +6,9 @@ php:
 
 before_install:
   - phpenv config-rm xdebug.ini
-  - composer self-update
 
 install:
-  - composer update --no-interaction
+  - composer install --no-interaction
 
 script:
   - composer test

LICENSE.md LICENSELICENSE.md renamed to LICENSE

@@ -1,7 +1,7 @@
 {
     "name": "php-ds/php-ds",
     "license": "MIT",
-    "keywords": ["php", "data structures", "polyfill"],
+    "keywords": ["php", "ds", "data structures", "polyfill"],
     "authors": [
         {
             "name": "Rudi Theunissen",
@@ -15,10 +15,10 @@
         "php-ds/tests": "^1.1"
     },
     "suggest": {
-        "ext-ds": "to improve performance and memory usage"
+        "ext-ds": "to improve performance and reduce memory usage"
     },
     "scripts": {
-        "test": "phpunit -c ./vendor/php-ds/tests/phpunit.xml"
+        "test": "phpunit"
     },
     "autoload": {
         "psr-4" : {

composer.json

@@ -0,0 +1,17 @@
+<phpunit bootstrap="vendor/autoload.php" colors="true">
+    <testsuites>
+        <testsuite>
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+    <filter>
+        <whitelist>
+            <directory>src</directory>
+        </whitelist>
+    </filter>
+    <logging>
+        <log type="coverage-html" target="build/logs/coverage"/>
+        <log type="coverage-text" target="build/logs/coverage.txt"/>
+        <log type="coverage-clover" target="build/logs/coverage.xml"/>
+    </logging>
+</phpunit>

phpunit.xml

@@ -2,14 +2,14 @@
 namespace Ds\Traits;
 
 /**
- * Capacity
- *
- * @package Ds\Traits
+ * Common to structures that deal with an internal capacity. While none of the
+ * PHP implementations actually make use of a capacity, it's important to keep
+ * consistent with the extension.
  */
 trait Capacity
 {
     /**
-     * @var int
+     * @var int internal capacity
      */
     private $capacity = self::MIN_CAPACITY;
 
@@ -37,23 +37,26 @@ public function allocate(int $capacity)
     }
 
     /**
-     * Increase Capacity
+     * Called when capacity should be increased to accommodate new values.
      */
-    abstract protected function increaseCapacity();
+    abstract protected function increaseCapacityWhenFull();
 
     /**
-     * Adjust Capacity
+     * Adjusts the structure's capacity according to its current size.
      */
     private function adjustCapacity()
     {
         $size = count($this);
 
-        if ($size >= $this->capacity) {
-            $this->increaseCapacity();
-
+        // Automatically truncate the allocated buffer when the size of the
+        // structure drops low enough.
+        if ($size < $this->capacity / 4) {
+            $this->capacity = max(self::MIN_CAPACITY, $this->capacity / 2);
         } else {
-            if ($size < $this->capacity / 4) {
-                $this->capacity = max(self::MIN_CAPACITY, $this->capacity / 2);
+
+            // Also check if we should increase capacity when the size changes.
+            while ($size >= $this->capacity) {
+                $this->increaseCapacityWhenFull();
             }
         }
     }

src/Traits/Capacity.php

@@ -2,9 +2,7 @@
 namespace Ds\Traits;
 
 /**
- * Collection
- *
- * @package Ds\Traits
+ * Common to structures that implement the base collection interface.
  */
 trait Collection
 {
@@ -14,27 +12,30 @@ trait Collection
      * This should be equivalent to a count of zero, but is not required.
      * Implementations should define what empty means in their own context.
      *
-     * @return bool
+     * @return bool whether the collection is empty.
      */
     public function isEmpty(): bool
     {
         return count($this) === 0;
     }
 
     /**
-     * Json Serialize
+     * Returns a representation that can be natively converted to JSON, which is
+     * called when invoking json_encode.
      *
-     * @return string
+     * @return mixed
+     *
+     * @see JsonSerializable
      */
     public function jsonSerialize()
     {
         return $this->toArray();
     }
 
     /**
-     * Creates a copy of the collection.
+     * Creates a shallow copy of the collection.
      *
-     * @return self
+     * @return \Ds\Collection a shallow copy of the collection.
      */
     public function copy(): \Ds\Collection
     {
@@ -44,24 +45,27 @@ public function copy(): \Ds\Collection
     /**
      * Returns an array representation of the collection.
      *
-     * The format of the returned array is implementation-dependent.
-     * Some implementations may throw an exception if an array representation
-     * could not be created.
+     * The format of the returned array is implementation-dependent. Some
+     * implementations may throw an exception if an array representation
+     * could not be created (for example when object are used as keys).
      *
      * @return array
      */
     abstract public function toArray(): array;
 
     /**
-     * Debug Info
+     * Invoked when calling var_dump.
+     *
+     * @return array
      */
     public function __debugInfo()
     {
         return $this->toArray();
     }
 
     /**
-     * To String
+     * Returns a string representation of the collection, which is invoked when
+     * the collection is converted to a string.
      */
     public function __toString()
     {

src/Traits/Collection.php

@@ -1,15 +1,14 @@
 <?php
 namespace Ds\Traits;
 
-use Error;
 use OutOfRangeException;
 use Traversable;
 use UnderflowException;
 
 /**
- * Sequence
- *
- * @package Ds\Traits
+ * Common functionality of all structures that implement 'Sequence'. Because the
+ * polyfill's only goal is to achieve consistent behaviour, all sequences will
+ * share the same implementation using an internal array.
  */
 trait Sequence
 {