From 7a8ac2f87a8198bf775fc0f66de2154ec370b7b2 Mon Sep 17 00:00:00 2001 From: Sebastian Meyer Date: Wed, 24 Jan 2024 22:45:04 +0100 Subject: [PATCH] Update PHPDoc --- src/DataStructures/StrictList.php | 62 ++++++++++------------- src/DataStructures/StrictQueue.php | 25 +++++++-- src/DataStructures/StrictStack.php | 23 ++++++++- src/ErrorHandlers/ThrowErrorException.php | 2 +- src/InterfaceTraits/ArrayAccess.php | 4 -- src/InterfaceTraits/Countable.php | 1 - src/InterfaceTraits/Iterator.php | 5 -- src/InterfaceTraits/IteratorAggregate.php | 1 - 8 files changed, 69 insertions(+), 54 deletions(-) diff --git a/src/DataStructures/StrictList.php b/src/DataStructures/StrictList.php index d954ae6..f5f80ee 100644 --- a/src/DataStructures/StrictList.php +++ b/src/DataStructures/StrictList.php @@ -46,25 +46,7 @@ class StrictList extends SplDoublyLinkedList use Getter; /** - * Defines the allowed types for items. - * - * If empty, all types are allowed. Possible values are: - * - "array" - * - "bool" - * - "callable" - * - "countable" - * - "float" or "double" - * - "int" or "integer" or "long" - * - "iterable" - * - "null" - * - "numeric" - * - "object" or FQCN - * - "resource" - * - "scalar" - * - "string" - * - * Fully qualified class names (FQCN) can be specified instead of the - * generic type "object". + * Defines the allowed data types for items. * * @var string[] */ @@ -72,7 +54,6 @@ class StrictList extends SplDoublyLinkedList /** * Add/insert a new item at the specified index. - * @see SplDoublyLinkedList::add() * * @param int $index The index where the new item is to be inserted * @param AllowedType $item The new item for the index @@ -122,11 +103,11 @@ class StrictList extends SplDoublyLinkedList } /** - * Check if item is an allowed type. + * Check if the item's data type is allowed on the list. * * @param AllowedType $item The item to check * - * @return bool Whether the item is an allowed type + * @return bool Whether the item's data type is allowed */ public function isAllowedType(mixed $item): bool { @@ -138,7 +119,7 @@ class StrictList extends SplDoublyLinkedList if (function_exists($function) && $function($item)) { return true; } - $fqcn = '\\' . ltrim($type, '\\'); + $fqcn = ltrim($type, '\\'); if (is_object($item) && is_a($item, $fqcn)) { return true; } @@ -148,9 +129,8 @@ class StrictList extends SplDoublyLinkedList /** * Magic getter method for $this->allowedTypes. - * @see Getter * - * @return string[] The list of allowed item types + * @return string[] The list of allowed data types * * @internal */ @@ -161,7 +141,6 @@ class StrictList extends SplDoublyLinkedList /** * Set the item at the specified index. - * @see \ArrayAccess::offsetSet() * * @param ?int $index The index being set or NULL to append * @param AllowedType $item The new item for the index @@ -212,7 +191,6 @@ class StrictList extends SplDoublyLinkedList /** * Push an item at the end of the list. - * @see SplDoublyLinkedList::push() * * @param AllowedType $item The item to push * @@ -235,9 +213,8 @@ class StrictList extends SplDoublyLinkedList /** * Get string representation of $this. - * @see \Serializable::serialize() * - * @return string String representation + * @return string The string representation */ public function serialize(): string { @@ -246,9 +223,8 @@ class StrictList extends SplDoublyLinkedList /** * Restore $this from string representation. - * @see \Serializable::unserialize() * - * @param string $data String representation + * @param string $data The string representation * * @return void */ @@ -261,7 +237,6 @@ class StrictList extends SplDoublyLinkedList /** * Prepend the list with an item. - * @see SplDoublyLinkedList::unshift() * * @param AllowedType $item The item to unshift * @@ -285,7 +260,22 @@ class StrictList extends SplDoublyLinkedList /** * Create a type-sensitive, traversable list of items. * - * @param string[] $allowedTypes Allowed types of items (optional) + * @param string[] $allowedTypes Allowed data types of items (optional) + * If empty, all types are allowed. + * Possible values are: + * - "array" + * - "bool" + * - "callable" + * - "countable" + * - "float" or "double" + * - "int" or "integer" or "long" + * - "iterable" + * - "null" + * - "numeric" + * - "object" or FQCN + * - "resource" + * - "scalar" + * - "string" * * @throws InvalidArgumentException */ @@ -302,7 +292,7 @@ class StrictList extends SplDoublyLinkedList /** * Get debug information for $this. * - * @return mixed[] Array of debug information + * @return mixed[] The debug information * * @internal */ @@ -314,7 +304,7 @@ class StrictList extends SplDoublyLinkedList /** * Get array representation of $this. * - * @return mixed[] Array representation + * @return mixed[] The array representation * * @internal */ @@ -330,7 +320,7 @@ class StrictList extends SplDoublyLinkedList /** * Restore $this from array representation. * - * @param mixed[] $data Array representation + * @param mixed[] $data The array representation * * @return void * diff --git a/src/DataStructures/StrictQueue.php b/src/DataStructures/StrictQueue.php index 187f987..9558b9c 100644 --- a/src/DataStructures/StrictQueue.php +++ b/src/DataStructures/StrictQueue.php @@ -28,6 +28,9 @@ use RuntimeException; /** * A type-sensitive, taversable First In, First Out Queue (FIFO). * + * Extends [\SplQueue](https://www.php.net/splqueue) with an option to specify + * the allowed data types for list items. + * * @author Sebastian Meyer * @package Basics\DataStructures * @@ -40,7 +43,6 @@ class StrictQueue extends StrictList { /** * Dequeue an item from the queue. - * @see \SplQueue::dequeue() * * @return AllowedType The dequeued item */ @@ -51,7 +53,6 @@ class StrictQueue extends StrictList /** * Add an item to the queue. - * @see \SplQueue::enqueue() * * @param AllowedType $item The item to enqueue * @@ -66,7 +67,6 @@ class StrictQueue extends StrictList /** * Set the mode of iteration. - * @see \SplDoublyLinkedList::setIteratorMode() * * @param int $mode The new iterator mode (0 or 1) * @@ -90,7 +90,24 @@ class StrictQueue extends StrictList /** * Create a type-sensitive, traversable queue of items. * - * @param string[] $allowedTypes Allowed types of items (optional) + * @param string[] $allowedTypes Allowed data types of items (optional) + * If empty, all types are allowed. + * Possible values are: + * - "array" + * - "bool" + * - "callable" + * - "countable" + * - "float" or "double" + * - "int" or "integer" or "long" + * - "iterable" + * - "null" + * - "numeric" + * - "object" or FQCN + * - "resource" + * - "scalar" + * - "string" + * + * @throws \InvalidArgumentException */ public function __construct(array $allowedTypes = []) { diff --git a/src/DataStructures/StrictStack.php b/src/DataStructures/StrictStack.php index 75be95b..e60e50b 100644 --- a/src/DataStructures/StrictStack.php +++ b/src/DataStructures/StrictStack.php @@ -28,6 +28,9 @@ use RuntimeException; /** * A type-sensitive, taversable Last In, First Out Stack (LIFO). * + * Extends [\SplStack](https://www.php.net/splstack) with an option to specify + * the allowed data types for list items. + * * @author Sebastian Meyer * @package Basics\DataStructures * @@ -64,7 +67,6 @@ class StrictStack extends StrictList /** * Set the mode of iteration. - * @see \SplDoublyLinkedList::setIteratorMode() * * @param int $mode The new iterator mode (2 or 3) * @@ -88,7 +90,24 @@ class StrictStack extends StrictList /** * Create a type-sensitive, traversable stack of items. * - * @param string[] $allowedTypes Allowed types of items (optional) + * @param string[] $allowedTypes Allowed data types of items (optional) + * If empty, all types are allowed. + * Possible values are: + * - "array" + * - "bool" + * - "callable" + * - "countable" + * - "float" or "double" + * - "int" or "integer" or "long" + * - "iterable" + * - "null" + * - "numeric" + * - "object" or FQCN + * - "resource" + * - "scalar" + * - "string" + * + * @throws \InvalidArgumentException */ public function __construct(array $allowedTypes = []) { diff --git a/src/ErrorHandlers/ThrowErrorException.php b/src/ErrorHandlers/ThrowErrorException.php index 04bd338..4e366fe 100644 --- a/src/ErrorHandlers/ThrowErrorException.php +++ b/src/ErrorHandlers/ThrowErrorException.php @@ -36,7 +36,7 @@ use ErrorException; class ThrowErrorException { /** - * Converts an internal PHP error into an ErrorException. + * Convert an internal PHP error into an ErrorException. * * @param int $errno The severity of the error * @param string $errstr The error message diff --git a/src/InterfaceTraits/ArrayAccess.php b/src/InterfaceTraits/ArrayAccess.php index 02a60dc..20e33da 100644 --- a/src/InterfaceTraits/ArrayAccess.php +++ b/src/InterfaceTraits/ArrayAccess.php @@ -40,7 +40,6 @@ trait ArrayAccess /** * Whether the specified offset exists. - * @see \ArrayAccess::offsetExists() * * @param mixed $offset The offset to check for * @@ -53,7 +52,6 @@ trait ArrayAccess /** * Retrieve data at the specified offset. - * @see \ArrayAccess::offsetGet() * * @param mixed $offset The offset to retrieve at * @@ -66,7 +64,6 @@ trait ArrayAccess /** * Assign a value to the specified offset. - * @see \ArrayAccess::offsetSet() * * @param mixed $offset The offset to assign to or NULL to append * @param mixed $value The value to set @@ -84,7 +81,6 @@ trait ArrayAccess /** * Unset the specified offset. - * @see \ArrayAccess::offsetUnset() * * @param mixed $offset The offset to unset * diff --git a/src/InterfaceTraits/Countable.php b/src/InterfaceTraits/Countable.php index fdfc231..5eb2660 100644 --- a/src/InterfaceTraits/Countable.php +++ b/src/InterfaceTraits/Countable.php @@ -40,7 +40,6 @@ trait Countable /** * Count the data items. - * @see \Countable::count() * * @return int The number of data items */ diff --git a/src/InterfaceTraits/Iterator.php b/src/InterfaceTraits/Iterator.php index 665c478..2c71bae 100644 --- a/src/InterfaceTraits/Iterator.php +++ b/src/InterfaceTraits/Iterator.php @@ -40,7 +40,6 @@ trait Iterator /** * Return the current item. - * @see \Iterator::current() * * @return mixed The current item or FALSE if invalid */ @@ -51,7 +50,6 @@ trait Iterator /** * Return the current key. - * @see \Iterator::key() * * @return mixed The current key or NULL if invalid */ @@ -62,7 +60,6 @@ trait Iterator /** * Move forward to next item. - * @see \Iterator::next() * * @return void */ @@ -73,7 +70,6 @@ trait Iterator /** * Rewind the iterator to the first item. - * @see \Iterator::rewind() * * @return void */ @@ -84,7 +80,6 @@ trait Iterator /** * Checks if current position is valid. - * @see \Iterator::valid() * * @return bool Whether the current position is valid */ diff --git a/src/InterfaceTraits/IteratorAggregate.php b/src/InterfaceTraits/IteratorAggregate.php index 9578a6b..571c503 100644 --- a/src/InterfaceTraits/IteratorAggregate.php +++ b/src/InterfaceTraits/IteratorAggregate.php @@ -42,7 +42,6 @@ trait IteratorAggregate /** * Retrieve an external iterator. - * @see \IteratorAggregate::getIterator() * * @return ArrayIterator */