Add PHPDocs

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

Author: coisa

src/CountableFilterIterator.php

@@ -21,6 +21,16 @@
 use Countable;
 use FilterIterator;
 
+/**
+ * Provides a filter iterator implementation that is also countable.
+ *
+ * This abstract class SHALL extend {@see FilterIterator} so that concrete
+ * implementations MAY filter elements from an inner iterator while also
+ * exposing count semantics. The counting behavior MUST be provided through
+ * the composed trait and SHALL operate according to the characteristics of
+ * the wrapped inner iterator. Implementations SHOULD ensure that their
+ * filtering logic remains consistent with the sequence being counted.
+ */
 abstract class CountableFilterIterator extends FilterIterator implements Countable
 {
     use CountableIteratorIteratorTrait;

src/CountableIterator.php

@@ -21,15 +21,27 @@
 use Countable;
 use Iterator;
 
+/**
+ * Provides a base iterator implementation that is also countable.
+ *
+ * This abstract class SHALL be used as a foundation for iterators that need
+ * to expose counting behavior while remaining compatible with the standard
+ * {@see Iterator} contract. Implementations MUST preserve iterator semantics,
+ * and consumers SHOULD expect the counting logic to operate over the same
+ * sequence that is exposed during normal iteration.
+ */
 abstract class CountableIterator implements Iterator, Countable
 {
     /**
-     * Counts the number of elements in the iterable.
+     * Counts the number of elements available in the iterator.
      *
-     * If the inner iterator implements Countable, it uses that. Otherwise, it
-     * counts the elements by iterating through them.
+     * This method MUST count the elements by iterating over a clone of the
+     * current iterator instance so that the active iterator state of the
+     * original object is not modified during the counting process. Concrete
+     * implementations SHOULD therefore remain safely cloneable whenever this
+     * behavior is expected to be used.
      *
-     * @return int the number of elements in the iterable
+     * @return int the total number of elements exposed by the iterator
      */
     public function count(): int
     {

src/CountableIteratorAggregate.php

@@ -22,12 +22,29 @@
 use IteratorAggregate;
 use Traversable;
 
+/**
+ * Provides a base implementation for iterator aggregate objects that are also countable.
+ *
+ * This abstract class SHALL serve as a reusable foundation for concrete iterator aggregate
+ * implementations that expose a traversable iterator and require count-related behavior.
+ * Implementations MUST provide a valid iterator through {@see getIterator()}, and that
+ * iterator SHOULD be suitable for reuse by the count-related logic provided through the
+ * composed trait.
+ */
 abstract class CountableIteratorAggregate implements IteratorAggregate, Countable
 {
     use CountableIteratorIteratorTrait;
 
     /**
-     * @return Traversable
+     * Returns the inner traversable iterator used by the aggregate.
+     *
+     * This method SHALL proxy the iterator returned by {@see getIterator()} without altering
+     * its semantics or traversal behavior. Consumers of this method MUST receive the same
+     * traversable instance or equivalent traversable representation exposed by the aggregate.
+     * This method SHOULD remain private because it exists only to support the internal
+     * collaboration between this class and its trait-based behavior.
+     *
+     * @return Traversable the traversable iterator exposed by the aggregate implementation
      */
     private function getInnerIterator(): Traversable
     {

src/CountableIteratorIterator.php

@@ -21,6 +21,14 @@
 use Countable;
 use IteratorIterator;
 
+/**
+ * Provides an iterator wrapper that is also countable.
+ *
+ * This class SHALL extend {@see IteratorIterator} to decorate an existing iterator while
+ * exposing counting behavior through the composed trait. The wrapped iterator MUST be
+ * compatible with the expectations of {@see IteratorIterator}, and consumers SHOULD rely
+ * on this class when they need both traversal and count semantics from a single object.
+ */
 class CountableIteratorIterator extends IteratorIterator implements Countable
 {
     use CountableIteratorIteratorTrait;

src/CountableIteratorIteratorTrait.php

@@ -22,15 +22,31 @@
 use Countable;
 use IteratorIterator;
 
+/**
+ * Provides counting behavior for iterators and iterator aggregates.
+ *
+ * This trait SHALL add a {@see count()} implementation that delegates to the
+ * inner iterator when possible. When the inner iterator does not implement
+ * {@see Countable}, the trait MUST determine whether the iterator can be safely
+ * cloned before counting its elements through traversal. Implementing classes
+ * MUST provide a compatible {@see getInnerIterator()} method that returns the
+ * traversable object to be counted.
+ */
 trait CountableIteratorIteratorTrait
 {
     /**
-     * Counts the number of elements in the iterable.
+     * Counts the number of elements exposed by the inner iterator.
      *
-     * If the inner iterator implements Countable, it uses that. Otherwise, it
-     * counts the elements by iterating through them.
+     * If the inner iterator implements {@see Countable}, this method SHALL
+     * return the value provided by that implementation. Otherwise, it MUST count
+     * elements by iterating over the iterator. If the inner iterator is not
+     * cloneable, this method SHALL wrap the current object in an
+     * {@see IteratorIterator} instance and count through that wrapper to avoid
+     * performing an invalid clone operation. If the inner iterator is cloneable,
+     * this method SHOULD count over a clone so that the original iterator state
+     * is preserved as much as possible.
      *
-     * @return int the number of elements in the iterable
+     * @return int the total number of elements available from the inner iterator
      */
     public function count(): int
     {