Update phpDoc

This commit is contained in:
Sebastian Meyer 2024-01-26 16:37:41 +01:00
parent 15222992f8
commit 11a7179c21
12 changed files with 81 additions and 175 deletions

View File

@ -3,9 +3,9 @@
{%
set topMenu = {
"menu": [
{ "name": "Packagist", "url": "https://packagist.org/packages/opencultureconsulting/basics"}
],
"social": [
{ "iconClass": "fab fa-php", "url": "https://packagist.org/packages/opencultureconsulting/basics"},
{ "iconClass": "fab fa-github", "url": "https://github.com/opencultureconsulting/php-basics"},
{ "iconClass": "fab fa-mastodon", "url": "https://openbiblio.social/@occ"},
{ "iconClass": "fas fa-envelope-open-text", "url": "mailto:office@opencultureconsulting.com"}

View File

@ -0,0 +1,31 @@
<input class="phpdocumentor-sidebar__menu-button" type="checkbox" id="sidebar-button" name="sidebar-button" />
<label class="phpdocumentor-sidebar__menu-icon" for="sidebar-button">
Menu
</label>
<aside class="phpdocumentor-column -three phpdocumentor-sidebar">
{% for version in project.versions %}
{% for toc in version.tableOfContents %}
<section class="phpdocumentor-sidebar__category">
<h2 class="phpdocumentor-sidebar__category-header">{{ toc.name|capitalize }}</h2>
{% for root in toc.roots %}
{{ toc(root, 'components/menu.html.twig', 1) }}
{% endfor %}
</section>
{% endfor %}
{% endfor %}
<section class="phpdocumentor-sidebar__category">
<h2 class="phpdocumentor-sidebar__category-header">Reports</h2>
{% if project.settings.custom['graphs.enabled'] %}
<h3 class="phpdocumentor-sidebar__root-package"><a href="graphs/classes.html">Class Diagram</a></h3>
{% endif %}
<h3 class="phpdocumentor-sidebar__root-package"><a href="reports/deprecated.html">Deprecated</a></h3>
<h3 class="phpdocumentor-sidebar__root-package"><a href="reports/errors.html">Errors</a></h3>
<h3 class="phpdocumentor-sidebar__root-package"><a href="reports/markers.html">Markers</a></h3>
</section>
<section class="phpdocumentor-sidebar__category">
<h2 class="phpdocumentor-sidebar__category-header">Indices</h2>
<h3 class="phpdocumentor-sidebar__root-package"><a href="indices/files.html">Files</a></h3>
</section>
</aside>

View File

@ -26,14 +26,14 @@
<ignore-tag>psalm-suppress</ignore-tag>
</ignore-tags>
</api>
<guide>
<guide format="rst">
<source dsn=".">
<path>/.phpdoc/guide</path>
</source>
<output>guides</output>
</guide>
</version>
<setting name="graphs.enabled" value="true"/>
<setting name="graphs.enabled" value="false"/>
<setting name="guides.enabled" value="true"/>
<setting name="template.color" value="orange"/>
</phpdocumentor>

View File

@ -6,7 +6,8 @@
errorLevel="1"
resolveFromConfigFile="true"
findUnusedBaselineEntry="true"
findUnusedCode="false"
findUnusedCode="true"
findUnusedVariablesAndParams="true"
>
<issueHandlers>
<RedundantCastGivenDocblockType errorLevel="suppress"/>

View File

@ -27,7 +27,6 @@ use ArrayAccess;
use Countable;
use InvalidArgumentException;
use Iterator;
use OutOfRangeException;
use RuntimeException;
use SplDoublyLinkedList;
use OCC\Basics\Traits\Getter;
@ -56,27 +55,7 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
use Getter;
/**
* Queue style iterator mode (First In, First Out).
*/
public const IT_MODE_FIFO = 0;
/**
* Stack style iterator mode (Last In, First Out).
*/
public const IT_MODE_LIFO = 2;
/**
* Destructive iterator mode (delete values after iteration).
*/
public const IT_MODE_DELETE = 1;
/**
* Preserving iterator mode (keep values after iteration).
*/
public const IT_MODE_KEEP = 0;
/**
* The allowed data types for values.
* The allowed data types for list values.
*
* @var string[]
*
@ -153,27 +132,15 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
}
/**
* Count the number of values on the list.
* Get allowed data types for list values.
*
* @return int The current number of values
* @return string[] The list of allowed data types
*
* @api
*/
public function count(): int
public function getAllowedTypes(): array
{
return parent::count();
}
/**
* Get current list value.
*
* @return AllowedType The current value
*
* @api
*/
public function current(): mixed
{
return parent::current();
return $this->allowedTypes;
}
/**
@ -216,30 +183,6 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
return false;
}
/**
* Check if the list is empty.
*
* @return bool Whether the list is empty
*
* @api
*/
public function isEmpty(): bool
{
return parent::isEmpty();
}
/**
* Get the current value's offset.
*
* @return int The current offset
*
* @api
*/
public function key(): int
{
return parent::key();
}
/**
* Magic getter method for $this->allowedTypes.
*
@ -249,49 +192,7 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
*/
protected function magicGetAllowedTypes(): array
{
return $this->allowedTypes;
}
/**
* Move cursor to the next value on the list.
*
* @return void
*
* @api
*/
public function next(): void
{
parent::next();
}
/**
* Check if the specified offset exists.
*
* @param int $offset The offset being checked
*
* @return bool Whether the offset exists
*
* @api
*/
public function offsetExists(mixed $offset): bool
{
return parent::offsetExists($offset);
}
/**
* Get the value at the specified offset.
*
* @param int $offset The offset to get
*
* @return ?AllowedType The value at the offset or NULL
*
* @throws OutOfRangeException
*
* @api
*/
public function offsetGet(mixed $offset): mixed
{
return parent::offsetGet($offset);
return $this->getAllowedTypes();
}
/**
@ -304,7 +205,7 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
*
* @throws InvalidArgumentException
*
* @api
* @internal
*/
public function offsetSet(mixed $offset, mixed $value): void
{
@ -320,22 +221,6 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
parent::offsetSet($offset, $value);
}
/**
* Unset the specified offset.
*
* @param int $offset The offset to unset
*
* @return void
*
* @throws OutOfRangeException
*
* @api
*/
public function offsetUnset(mixed $offset): void
{
parent::offsetUnset($offset);
}
/**
* Pops an value from the end of the list.
*
@ -379,18 +264,6 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
}
}
/**
* Move cursor to the previous value on the list.
*
* @return void
*
* @api
*/
public function prev(): void
{
parent::prev();
}
/**
* Push an value at the end of the list.
*
@ -415,18 +288,6 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
parent::push($value);
}
/**
* Move cursor back to the start of the list.
*
* @return void
*
* @api
*/
public function rewind(): void
{
parent::rewind();
}
/**
* Get string representation of $this.
*
@ -447,8 +308,6 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
* @return void
*
* @throws InvalidArgumentException
*
* @internal
*/
protected function setAllowedTypes(array $allowedTypes = []): void
{
@ -554,18 +413,6 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
parent::unshift($value);
}
/**
* Check if the list contains any more values.
*
* @return bool Whether the list contains more values
*
* @api
*/
public function valid(): bool
{
return parent::valid();
}
/**
* Create a type-sensitive, traversable list of values.
*

View File

@ -51,6 +51,8 @@ class StrictQueue extends StrictList implements ArrayAccess, Countable, Iterator
* Dequeue an item from the queue.
*
* @return AllowedType The dequeued item
*
* @api
*/
public function dequeue(): mixed
{
@ -65,6 +67,8 @@ class StrictQueue extends StrictList implements ArrayAccess, Countable, Iterator
* @return void
*
* @throws \InvalidArgumentException
*
* @api
*/
public function enqueue(mixed $item): void
{
@ -90,6 +94,8 @@ class StrictQueue extends StrictList implements ArrayAccess, Countable, Iterator
* @return int The set of flags and modes of iteration
*
* @throws RuntimeException
*
* @api
*/
final public function setIteratorMode(int $mode): int
{

View File

@ -55,6 +55,8 @@ class StrictStack extends StrictList implements ArrayAccess, Countable, Iterator
* @return void
*
* @throws \InvalidArgumentException
*
* @api
*/
public function stack(mixed $item): void
{
@ -65,6 +67,8 @@ class StrictStack extends StrictList implements ArrayAccess, Countable, Iterator
* Unstack an item from the stack.
*
* @return AllowedType The unstacked item
*
* @api
*/
public function unstack(): mixed
{
@ -90,6 +94,8 @@ class StrictStack extends StrictList implements ArrayAccess, Countable, Iterator
* @return int The set of flags and modes of iteration
*
* @throws RuntimeException
*
* @api
*/
final public function setIteratorMode(int $mode): int
{

View File

@ -33,6 +33,7 @@ use ArrayAccess;
*
* @template TKey of int|string
* @template TValue of mixed
* @template TData of array<TKey, TValue>
* @implements ArrayAccess<TKey, TValue>
* @phpstan-require-implements ArrayAccess
*/
@ -41,7 +42,7 @@ trait ArrayAccessTrait
/**
* Holds the array-accessible data.
*
* @var array<TKey, TValue>
* @var TData
*/
protected array $data = [];

View File

@ -33,6 +33,7 @@ use Countable;
*
* @template TKey of int|string
* @template TValue of mixed
* @template TData of array<TKey, TValue>
* @implements Countable<TValue>
* @phpstan-require-implements Countable
*/
@ -41,7 +42,7 @@ trait CountableTrait
/**
* Holds the countable data.
*
* @var array<TKey, TValue>
* @var TData
*/
protected array $data = [];

View File

@ -34,6 +34,7 @@ use IteratorAggregate;
*
* @template TKey of int|string
* @template TValue of mixed
* @template TData of array<TKey, TValue>
* @implements IteratorAggregate<TKey, TValue>
* @phpstan-require-implements IteratorAggregate
*/
@ -42,7 +43,7 @@ trait IteratorAggregateTrait
/**
* Holds the iterable data.
*
* @var array<TKey, TValue>
* @var TData
*/
protected array $data = [];

View File

@ -33,6 +33,7 @@ use Iterator;
*
* @template TKey of int|string
* @template TValue of mixed
* @template TData of array<TKey, TValue>
* @implements Iterator<TKey, TValue>
* @phpstan-require-implements Iterator
*/
@ -41,7 +42,7 @@ trait IteratorTrait
/**
* Holds the iterable data.
*
* @var array<TKey, TValue>
* @var TData
*/
protected array $data = [];
@ -75,6 +76,16 @@ trait IteratorTrait
next($this->data);
}
/**
* Move back to previous item.
*
* @return void
*/
public function prev(): void
{
prev($this->data);
}
/**
* Rewind the iterator to the first item.
*

View File

@ -23,7 +23,6 @@ declare(strict_types=1);
namespace OCC\Basics\Traits;
use Exception;
use LogicException;
/**
@ -38,6 +37,8 @@ trait Singleton
* Holds the singleton instance.
*
* @var array<string, static>
*
* @internal
*/
private static array $singleton = [];
@ -48,16 +49,12 @@ trait Singleton
*
* @return static The singleton instance
*
* @throws Exception
* @api
*/
final public static function getInstance(mixed ...$args): static
{
if (!isset(static::$singleton[static::class])) {
try {
static::$singleton[static::class] = new static(...$args);
} catch (Exception $exception) {
throw $exception;
}
}
return static::$singleton[static::class];
}
@ -66,12 +63,16 @@ trait Singleton
* This is a singleton class, thus the constructor is private.
*
* Usage: Get an instance of this class by calling static::getInstance()
*
* @return void
*/
abstract private function __construct();
/**
* This is a singleton class, thus cloning is prohibited.
*
* @return void
*
* @throws LogicException
*
* @internal