Improve documentation (#125)

* Test documentation has sections for all public methods
* Improve documentation

Author: sanmai

README.md

@@ -113,12 +113,17 @@ All entry points always return an instance of the pipeline.
 | `prepend()` | Appends the contents of an interable to the end of the pipeline. | `array_merge` |
 | `unshift()` | Prepends the pipeline with a list of values. | `array_unshift` |
 | `zip()`  | Takes a number of iterables, transposing them together with the current sequence, if any.  | `array_map(null, ...$array)`, Python's `zip()`, transposition |
+| `reservoir()` | Reservoir sampling with an optional weighting function. |  |
 | `flatten()` |  Flattens inputs: `[[1, 2], [3, 4]]` becomes `[1, 2, 3, 4]`. |  `flat_map`, `flatten`, `collect_concat`      |
 | `unpack()`  | Unpacks arrays into arguments for a callback. Flattens inputs if no callback provided. |             |
 | `chunk()` | Chunks the pipeline into arrays of specified length. | `array_chunk` |
 | `filter()`  | Removes elements unless a callback returns true. Removes falsey values if no callback provided.  |  `array_filter`, `Where`                |
 | `slice()`  | Extracts a slice from the inputs. Keys are not discarded intentionally. Suppors negative values for both arguments. |  `array_slice`                |
-| `reduce()`  | Reduces input values to a single value. Defaults to summation. Requires an initial value. | `array_reduce`, `Aggregate`, `Sum` |
+| `fold()`  | Reduces input values to a single value. Defaults to summation. Requires an initial value. | `array_reduce`, `Aggregate`, `Sum` |
+| `reduce()`  | Alias to `fold()` with a reversed order of arguments. | `array_reduce` |
+| `flip()`    | Swaps keys and values. | `array_flip` |
+| `max()`     | Finds the highest value. | `max` |
+| `min()`     | Finds the lowest value. | `min` |
 | `toArray()` | Returns an array with all values. Eagerly executed. | `dict`, `ToDictionary` |
 | `__construct()` | Can be provided with an optional initial iterator. Used in the `take()` function from above.  |     |
 

tests/DocumentationTest.php

@@ -0,0 +1,112 @@
+<?php
+/**
+ * Copyright 2017, 2018 Alexey Kopytko <[email protected]>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+declare(strict_types=1);
+
+namespace Tests\Pipeline;
+
+use PHPUnit\Framework\ExpectationFailedException;
+use PHPUnit\Framework\TestCase;
+use Pipeline\Standard;
+use ReflectionClass;
+use ReflectionMethod;
+use function file_get_contents;
+use function implode;
+use function Pipeline\take;
+use function preg_match_all;
+use function sprintf;
+use function strpos;
+use function substr;
+
+/**
+ * Test documentation has sections for all public methods.
+ *
+ * @coversNothing
+ *
+ * @internal
+ */
+final class DocumentationTest extends TestCase
+{
+    private static string $readme;
+    private static string $headers;
+
+    public static function setUpBeforeClass(): void
+    {
+        self::$readme = file_get_contents(__DIR__.'/../README.md');
+
+        preg_match_all('/^#.*/m', self::$readme, $matches);
+        self::$headers = implode("\n", $matches[0]);
+    }
+
+    /**
+     * @param array<ReflectionClass> $interfaces
+     */
+    private static function interfaceFilter(array $interfaces, ReflectionMethod $method): bool
+    {
+        foreach ($interfaces as $interface) {
+            if ($interface->hasMethod($method->getName())) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    public static function provideMethods(): iterable
+    {
+        $reflection = new ReflectionClass(new Standard());
+        $interfaces = $reflection->getInterfaces();
+
+        return take($reflection->getMethods(ReflectionMethod::IS_PUBLIC))
+            ->filter(fn (ReflectionMethod $method) => self::interfaceFilter($interfaces, $method))
+            ->cast(fn (ReflectionMethod $method) => [$method->getName()]);
+    }
+
+    /**
+     * @dataProvider provideMethods
+     */
+    public function testMethodHasMention(string $methodName): void
+    {
+        try {
+            $this->assertMatchesRegularExpression(
+                sprintf('/`%s\(\)`/', $methodName),
+                self::$readme,
+                "There's no mention of {$methodName}."
+            );
+        } catch (ExpectationFailedException $e) {
+            $message = $e->getMessage();
+            $this->fail(substr($message, 0, strpos($message, "\n")));
+        }
+    }
+
+    /**
+     * @dataProvider provideMethods
+     */
+    public function testMethodHasHeader(string $methodName): void
+    {
+        try {
+            $this->assertMatchesRegularExpression(
+                sprintf('/^##.*(->|`)%s\(\)`/m', $methodName),
+                self::$headers,
+                "There's no header dedicated to {$methodName}."
+            );
+        } catch (ExpectationFailedException $e) {
+            $message = $e->getMessage();
+            $this->markTestIncomplete(substr($message, 0, strpos($message, "\n")));
+        }
+    }
+}