Update documentation

opencultureconsulting · Feb 15, 2024 · 887a7af · 887a7af
1 parent 8d0ca2d
commit 887a7af
Show file tree

Hide file tree

Showing 77 changed files with 3,538 additions and 554 deletions.
diff --git a/.phpdoc/guide/changelog.rst b/.phpdoc/guide/changelog.rst
@@ -0,0 +1,74 @@
+.. title:: Changelog
+
+Changelog
+#########
+
+* :ref:`v2-0-0`
+* :ref:`v1-1-0`
+* :ref:`v1-0-1`
+* :ref:`v1-0-0`
+
+.. _v2-0-0:
+
+v2.0.0
+======
+
+**Breaking Changes:**
+
+* Raised minimum PHP version from 8.0 to 8.1
+* Renamed traits for :php:namespace:`OCC\Basics\Interfaces` and moved to different namespace
+* Renamed internal methods for :php:trait:`OCC\Basics\Traits\Getter` and :php:trait:`OCC\Basics\Traits\Setter` to avoid
+  confusion with regular class method
+
+  .. code-block:: php
+    // old methods
+    protected function magicGet{PascalCasePropertyName}(): mixed
+    protected function magicSet{PascalCasePropertyName}(mixed $value): void
+
+  .. code-block:: php
+    // new methods
+    protected function _magicGet{PascalCasePropertyName}(): mixed
+    protected function _magicSet{PascalCasePropertyName}(mixed $value): void
+
+**New Features:**
+
+* Added new datastructure :php:class:`OCC\Basics\DataStructures\StrictCollection`
+* Added new error handler :php:class:`OCC\Basics\ErrorHandlers\TriggerExceptionError`
+* Added new trait :php:trait:`OCC\Basics\Traits\OverloadingGetter`
+* Added new trait :php:trait:`OCC\Basics\Traits\OverloadingSetter`
+* Extended API for all datastructures
+* Extended `documentation <https://opencultureconsulting.github.io/basics/>`_
+
+.. _v1-1-0:
+
+v1.1.0
+======
+
+**Breaking Changes:**
+
+* Changed the constructor's signature for all :php:namespace:`OCC\Basics\DataStructures` to improve compatibility with
+  the corresponding `SPL datastructures <https://www.php.net/spl.datastructures>`_
+
+  .. code-block:: php
+    // old constructor signature
+    public function __construct(iterable $items = [], array $allowedTypes = [])
+
+  .. code-block:: php
+    // new constructor signature
+    public function __construct(array $allowedTypes = [])
+
+.. _v1-0-1:
+
+v1.0.1
+======
+
+**New Features:**
+
+* Improved exception handling in :php:trait:`Singleton <OCC\Basics\Traits\Singleton>` trait
+
+.. _v1-0-0:
+
+v1.0.0
+======
+
+**Initial Release**
diff --git a/.phpdoc/guide/changelog/index.rst b/.phpdoc/guide/changelog/index.rst
diff --git a/.phpdoc/guide/changelog/v1.0.0.rst b/.phpdoc/guide/changelog/v1.0.0.rst
diff --git a/.phpdoc/guide/changelog/v1.0.1.rst b/.phpdoc/guide/changelog/v1.0.1.rst
diff --git a/.phpdoc/guide/changelog/v1.1.0.rst b/.phpdoc/guide/changelog/v1.1.0.rst
diff --git a/.phpdoc/guide/index.rst b/.phpdoc/guide/index.rst
@@ -1,3 +1,5 @@
+.. title:: PHP Basics
+
 Documentation
 #############
 
@@ -8,5 +10,6 @@ Documentation
     :hidden:
     :titlesonly:
 
-    installation/index
-    changelog/index
+    overview/index
+    usage/index
+    changelog
diff --git a/.phpdoc/guide/installation/index.rst b/.phpdoc/guide/installation/index.rst
diff --git a/.phpdoc/guide/installation/test.rst b/.phpdoc/guide/installation/test.rst
diff --git a/.phpdoc/guide/overview/index.rst b/.phpdoc/guide/overview/index.rst
@@ -0,0 +1,4 @@
+.. title:: Overview
+
+Overview
+########
diff --git a/.phpdoc/guide/usage/index.rst b/.phpdoc/guide/usage/index.rst
@@ -0,0 +1,10 @@
+.. title:: User Guide
+
+User Guide
+##########
+
+.. toctree::
+    :maxdepth: 2
+
+    requirements
+    installation
diff --git a/.phpdoc/guide/usage/installation.rst b/.phpdoc/guide/usage/installation.rst
@@ -0,0 +1,8 @@
+.. title:: Installation
+
+Installation
+############
+
+.. code-block:: shell
+
+    composer require opencultureconsulting/basics
diff --git a/.phpdoc/guide/usage/requirements.rst b/.phpdoc/guide/usage/requirements.rst
@@ -0,0 +1,7 @@
+.. title:: Requirements
+
+Requirements
+############
+
+PHP 8.1
+Composer 2
diff --git a/.phpdoc/template/components/sidebar.html.twig b/.phpdoc/template/components/sidebar.html.twig
@@ -24,8 +24,8 @@
         <h3 class="phpdocumentor-sidebar__root-package"><a href="reports/markers.html">Markers</a></h3>
     </section>
 
-    <section class="phpdocumentor-sidebar__category -index">
-        <h2 class="phpdocumentor-sidebar__category-header">Index</h2>
+    <section class="phpdocumentor-sidebar__category -indices">
+        <h2 class="phpdocumentor-sidebar__category-header">Indices</h2>
         <h3 class="phpdocumentor-sidebar__root-package"><a href="indices/files.html">Files</a></h3>
     </section>
 </aside>
diff --git a/.phpdoc/template/css/custom.css.twig b/.phpdoc/template/css/custom.css.twig
@@ -29,7 +29,7 @@ aside.phpdocumentor-sidebar
 }
 
 aside.phpdocumentor-sidebar
-    section.-index
+    section.-indices
 {
     order: 5;
 }

diff --git a/doc/classes/OCC-Basics-DataStructures-StrictCollection.html b/doc/classes/OCC-Basics-DataStructures-StrictCollection.html
@@ -71,24 +71,32 @@ <h1 class="phpdocumentor-title"><a href="" class="phpdocumentor-title__link">PHP
     Menu
 </label>
 <aside class="phpdocumentor-column -three phpdocumentor-sidebar">
-                    <section class="phpdocumentor-sidebar__category">
-            <h2 class="phpdocumentor-sidebar__category-header">documentation</h2>
+                    <section class="phpdocumentor-sidebar__category -documentation">
+            <h2 class="phpdocumentor-sidebar__category-header">Documentation</h2>
                                     <h4 class="phpdocumentor-sidebar__root-namespace">
-    <a href="guides/installation/index.html#installation" class="">Installation</a>
+    <a href="guides/overview/index.html#overview" class="">Overview</a>
+</h4>
+
+                                    <h4 class="phpdocumentor-sidebar__root-namespace">
+    <a href="guides/usage/index.html#user-guide" class="">User Guide</a>
 </h4>
     <ul class="phpdocumentor-list">
                     <li>
-                <a href="guides/installation/test.html#test" class="">Test</a>
+                <a href="guides/usage/requirements.html#requirements" class="">Requirements</a>
+
+            </li>
+                    <li>
+                <a href="guides/usage/installation.html#installation" class="">Installation</a>
 
             </li>
             </ul>
 
                                     <h4 class="phpdocumentor-sidebar__root-namespace">
-    <a href="guides/changelog/index.html#changelog" class="">Changelog</a>
+    <a href="guides/changelog.html#changelog" class="">Changelog</a>
 </h4>
 
                         </section>
-                <section class="phpdocumentor-sidebar__category">
+                <section class="phpdocumentor-sidebar__category -namespaces">
             <h2 class="phpdocumentor-sidebar__category-header">Namespaces</h2>
                                     <h4 class="phpdocumentor-sidebar__root-namespace">
     <a href="namespaces/occ.html" class="">OCC</a>
@@ -101,7 +109,7 @@ <h4 class="phpdocumentor-sidebar__root-namespace">
             </ul>
 
                         </section>
-                <section class="phpdocumentor-sidebar__category">
+                <section class="phpdocumentor-sidebar__category -packages">
             <h2 class="phpdocumentor-sidebar__category-header">Packages</h2>
                                     <h4 class="phpdocumentor-sidebar__root-namespace">
     <a href="packages/Basics.html" class="">Basics</a>
@@ -127,15 +135,15 @@ <h4 class="phpdocumentor-sidebar__root-namespace">
 
                         </section>
 
-    <section class="phpdocumentor-sidebar__category">
+    <section class="phpdocumentor-sidebar__category -reports">
         <h2 class="phpdocumentor-sidebar__category-header">Reports</h2>
                 <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>
+    <section class="phpdocumentor-sidebar__category -index">
+        <h2 class="phpdocumentor-sidebar__category-header">Index</h2>
         <h3 class="phpdocumentor-sidebar__root-package"><a href="indices/files.html">Files</a></h3>
     </section>
 </aside>
@@ -1846,6 +1854,17 @@ <h5 class="phpdocumentor-tag-list__heading" id="tags">
     <section class="phpdocumentor-search-results__dialog">
         <header class="phpdocumentor-search-results__header">
             <h2 class="phpdocumentor-search-results__title">Search results</h2>
+            <section data-search-form class="phpdocumentor-search">
+    <label>
+        <span class="visually-hidden">Search for</span>
+        <svg class="phpdocumentor-search__icon" width="21" height="20" viewBox="0 0 21 20" fill="none" xmlns="http://www.w3.org/2000/svg">
+            <circle cx="7.5" cy="7.5" r="6.5" stroke="currentColor" stroke-width="2"/>
+            <line x1="12.4892" y1="12.2727" x2="19.1559" y2="18.9393" stroke="currentColor" stroke-width="3"/>
+        </svg>
+        <input type="search" class="phpdocumentor-field phpdocumentor-search__field" placeholder="Loading .." disabled />
+    </label>
+</section>
+
             <button class="phpdocumentor-search-results__close"><i class="fas fa-times"></i></button>
         </header>
         <section class="phpdocumentor-search-results__body">

diff --git a/doc/classes/OCC-Basics-DataStructures-StrictList.html b/doc/classes/OCC-Basics-DataStructures-StrictList.html
@@ -71,24 +71,32 @@ <h1 class="phpdocumentor-title"><a href="" class="phpdocumentor-title__link">PHP
     Menu
 </label>
 <aside class="phpdocumentor-column -three phpdocumentor-sidebar">
-                    <section class="phpdocumentor-sidebar__category">
-            <h2 class="phpdocumentor-sidebar__category-header">documentation</h2>
+                    <section class="phpdocumentor-sidebar__category -documentation">
+            <h2 class="phpdocumentor-sidebar__category-header">Documentation</h2>
                                     <h4 class="phpdocumentor-sidebar__root-namespace">
-    <a href="guides/installation/index.html#installation" class="">Installation</a>
+    <a href="guides/overview/index.html#overview" class="">Overview</a>
+</h4>
+
+                                    <h4 class="phpdocumentor-sidebar__root-namespace">
+    <a href="guides/usage/index.html#user-guide" class="">User Guide</a>
 </h4>
     <ul class="phpdocumentor-list">
                     <li>
-                <a href="guides/installation/test.html#test" class="">Test</a>
+                <a href="guides/usage/requirements.html#requirements" class="">Requirements</a>
+
+            </li>
+                    <li>
+                <a href="guides/usage/installation.html#installation" class="">Installation</a>
 
             </li>
             </ul>
 
                                     <h4 class="phpdocumentor-sidebar__root-namespace">
-    <a href="guides/changelog/index.html#changelog" class="">Changelog</a>
+    <a href="guides/changelog.html#changelog" class="">Changelog</a>
 </h4>
 
                         </section>
-                <section class="phpdocumentor-sidebar__category">
+                <section class="phpdocumentor-sidebar__category -namespaces">
             <h2 class="phpdocumentor-sidebar__category-header">Namespaces</h2>
                                     <h4 class="phpdocumentor-sidebar__root-namespace">
     <a href="namespaces/occ.html" class="">OCC</a>
@@ -101,7 +109,7 @@ <h4 class="phpdocumentor-sidebar__root-namespace">
             </ul>
 
                         </section>
-                <section class="phpdocumentor-sidebar__category">
+                <section class="phpdocumentor-sidebar__category -packages">
             <h2 class="phpdocumentor-sidebar__category-header">Packages</h2>
                                     <h4 class="phpdocumentor-sidebar__root-namespace">
     <a href="packages/Basics.html" class="">Basics</a>
@@ -127,15 +135,15 @@ <h4 class="phpdocumentor-sidebar__root-namespace">
 
                         </section>
 
-    <section class="phpdocumentor-sidebar__category">
+    <section class="phpdocumentor-sidebar__category -reports">
         <h2 class="phpdocumentor-sidebar__category-header">Reports</h2>
                 <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>
+    <section class="phpdocumentor-sidebar__category -index">
+        <h2 class="phpdocumentor-sidebar__category-header">Index</h2>
         <h3 class="phpdocumentor-sidebar__root-package"><a href="indices/files.html">Files</a></h3>
     </section>
 </aside>
@@ -2775,6 +2783,17 @@ <h5 class="phpdocumentor-tag-list__heading" id="tags">
     <section class="phpdocumentor-search-results__dialog">
         <header class="phpdocumentor-search-results__header">
             <h2 class="phpdocumentor-search-results__title">Search results</h2>
+            <section data-search-form class="phpdocumentor-search">
+    <label>
+        <span class="visually-hidden">Search for</span>
+        <svg class="phpdocumentor-search__icon" width="21" height="20" viewBox="0 0 21 20" fill="none" xmlns="http://www.w3.org/2000/svg">
+            <circle cx="7.5" cy="7.5" r="6.5" stroke="currentColor" stroke-width="2"/>
+            <line x1="12.4892" y1="12.2727" x2="19.1559" y2="18.9393" stroke="currentColor" stroke-width="3"/>
+        </svg>
+        <input type="search" class="phpdocumentor-field phpdocumentor-search__field" placeholder="Loading .." disabled />
+    </label>
+</section>
+
             <button class="phpdocumentor-search-results__close"><i class="fas fa-times"></i></button>
         </header>
         <section class="phpdocumentor-search-results__body">