From 4b02d4f0e60fd296acc155212a7b726f17811161 Mon Sep 17 00:00:00 2001 From: Sebastian Meyer Date: Wed, 15 Nov 2023 12:01:21 +0100 Subject: [PATCH] Improve phpDoc documentation --- CONTRIBUTING.md | 2 +- src/DataStructures/StrictList.php | 47 ++++++++++++++------------- src/DataStructures/StrictQueue.php | 2 +- src/DataStructures/StrictStack.php | 2 +- src/Functions/throwErrorException.php | 13 ++++---- src/Traits/Singleton.php | 3 +- 6 files changed, 36 insertions(+), 33 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 50e3655..fda8450 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,3 @@ Please read the excellent [GitHub Open Source Guide](https://opensource.guide/how-to-contribute/) on *How to Contribute on Open Source*. -If you have any further questions just [open a new issue](https://github.com/opencultureconsulting/php-traits/issues/new) and I'll be happy to assist! +If you have any further questions just [open a new issue](https://github.com/opencultureconsulting/php-basics/issues/new) and I'll be happy to assist! diff --git a/src/DataStructures/StrictList.php b/src/DataStructures/StrictList.php index 800a471..f5fe13e 100644 --- a/src/DataStructures/StrictList.php +++ b/src/DataStructures/StrictList.php @@ -43,29 +43,30 @@ class StrictList extends SplDoublyLinkedList /** * 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". + * + * 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". */ protected array $allowedTypes = []; /** * Add/insert a new item at the specified index. - * @see SplDoublyLinkedList::add + * @see SplDoublyLinkedList::add() * * @param int $index The index where the new item is to be inserted * @param mixed $item The new item for the index @@ -151,7 +152,7 @@ class StrictList extends SplDoublyLinkedList /** * Set the item at the specified index. - * @see ArrayAccess::offsetSet + * @see ArrayAccess::offsetSet() * * @param ?int $index The index being set or NULL to append * @param mixed $item The new item for the index @@ -191,7 +192,7 @@ class StrictList extends SplDoublyLinkedList /** * Push an item at the end of the list. - * @see SplDoublyLinkedList::push + * @see SplDoublyLinkedList::push() * * @param mixed $item The item to push * @@ -209,7 +210,7 @@ class StrictList extends SplDoublyLinkedList /** * Get string representation of $this. - * @see Serializable::serialize + * @see Serializable::serialize() * * @return string String representation */ @@ -220,7 +221,7 @@ class StrictList extends SplDoublyLinkedList /** * Restore $this from string representation. - * @see Serializable::unserialize + * @see Serializable::unserialize() * * @param string $data String representation * @@ -233,7 +234,7 @@ class StrictList extends SplDoublyLinkedList /** * Prepend the list with an item. - * @see SplDoublyLinkedList::unshift + * @see SplDoublyLinkedList::unshift() * * @param mixed $item The item to unshift * diff --git a/src/DataStructures/StrictQueue.php b/src/DataStructures/StrictQueue.php index daa065c..514a1b2 100644 --- a/src/DataStructures/StrictQueue.php +++ b/src/DataStructures/StrictQueue.php @@ -39,7 +39,7 @@ class StrictQueue extends StrictList { /** * Set the mode of iteration. - * @see SplDoublyLinkedList::setIteratorMode + * @see SplDoublyLinkedList::setIteratorMode() * * @param int $mode The new iterator mode (0 or 1) * diff --git a/src/DataStructures/StrictStack.php b/src/DataStructures/StrictStack.php index 71f73c6..516efbd 100644 --- a/src/DataStructures/StrictStack.php +++ b/src/DataStructures/StrictStack.php @@ -39,7 +39,7 @@ class StrictStack extends StrictList { /** * Set the mode of iteration. - * @see SplDoublyLinkedList::setIteratorMode + * @see SplDoublyLinkedList::setIteratorMode() * * @param int $mode The new iterator mode (2 or 3) * diff --git a/src/Functions/throwErrorException.php b/src/Functions/throwErrorException.php index 5eb94a2..738a2cb 100644 --- a/src/Functions/throwErrorException.php +++ b/src/Functions/throwErrorException.php @@ -25,25 +25,26 @@ namespace OCC\Basics\Functions; use ErrorException; /** - * Handles an internal PHP error and throws it as ErrorException. - * @example set_error_handler('\\OCC\\Basics\\Functions\\throwErrorException'); + * Converts an internal PHP error into an ErrorException. + * + * Usage: set_error_handler('\\OCC\\Basics\\Functions\\throwErrorException'); * * @author Sebastian Meyer * @package opencultureconsulting/basics * * @param int $severity The severity of the error * @param string $message The error message - * @param ?string $filename The name of the file the error was raised in - * @param ?int $line The number of the line the error was raised in + * @param ?string $file The name of the file the error was raised in + * @param ?int $line The line number the error was raised in * * @return bool Always returns FALSE when not throwing an exception * * @throws \ErrorException */ -function throwErrorException(int $severity = E_ALL, string $message = '', ?string $filename = null, ?int $line = null): bool +function throwErrorException(int $severity = E_ALL, string $message = '', ?string $file = null, ?int $line = null): bool { if (error_reporting() & $severity) { - throw new ErrorException($message, 0, $severity, $filename, $line); + throw new ErrorException($message, 0, $severity, $file, $line); } return false; } diff --git a/src/Traits/Singleton.php b/src/Traits/Singleton.php index 3e21c83..9d5cf60 100644 --- a/src/Traits/Singleton.php +++ b/src/Traits/Singleton.php @@ -52,7 +52,8 @@ trait Singleton /** * This is a singleton class, thus the constructor is private. - * (Get an instance of this class by calling self::getInstance()) + * + * Usage: Get an instance of this class by calling self::getInstance() * * @param mixed ...$args Constructor parameters */