From 02a108aac2a86a35b16c3f2c92b35816fff5d5ec Mon Sep 17 00:00:00 2001
From: Sebastian Meyer <sebastian@informathekar.de>
Date: Sun, 11 Feb 2024 17:33:36 +0100
Subject: [PATCH] Update phpDoc for Getter and Setter traits

---
 src/Traits/Getter.php    | 18 ++++++++++++------
 src/Traits/Setter.php    | 20 ++++++++++++--------
 src/Traits/Singleton.php |  2 +-
 3 files changed, 25 insertions(+), 15 deletions(-)

diff --git a/src/Traits/Getter.php b/src/Traits/Getter.php
index 5ad7f6d..9fa98e9 100644
--- a/src/Traits/Getter.php
+++ b/src/Traits/Getter.php
@@ -28,6 +28,15 @@ use InvalidArgumentException;
 /**
  * Reads data from inaccessible properties by using magic methods.
  *
+ * To make a `protected` or `private` property readable, provide a method named
+ * `_magicGet{Property}()` which handles the reading. Replace `{Property}` in
+ * the method's name with the name of the actual property (with an uppercase
+ * first letter).
+ *
+ * > Example: If the property is named `$fooBar`, the "magic" method has to be
+ * > `_magicGetFooBar()`. This method is then called when `$fooBar` is read
+ * > from outside the class context.
+ *
  * @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
  * @package Basics\Traits
  */
@@ -40,17 +49,14 @@ trait Getter
      *
      * @return mixed The class property's current value
      *
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException if the property does not exist
      *
      * @internal
      */
     public function __get(string $property): mixed
     {
-        $method = 'magicGet' . ucfirst($property);
-        if (
-            property_exists(static::class, $property)
-            && method_exists(static::class, $method)
-        ) {
+        $method = '_magicGet' . ucfirst($property);
+        if (property_exists(static::class, $property) && method_exists(static::class, $method)) {
             return $this->$method();
         } else {
             throw new InvalidArgumentException(
diff --git a/src/Traits/Setter.php b/src/Traits/Setter.php
index a44cd5e..8f35683 100644
--- a/src/Traits/Setter.php
+++ b/src/Traits/Setter.php
@@ -28,6 +28,15 @@ use InvalidArgumentException;
 /**
  * Writes data to inaccessible properties by using magic methods.
  *
+ * To make a `protected` or `private` property writable, provide a method named
+ * `_magicSet{Property}()` which handles the writing. Replace `{Property}` in
+ * the method's name with the name of the actual property (with an uppercase
+ * first letter).
+ *
+ * > Example: If the property is named `$fooBar`, the "magic" method has to be
+ * > `_magicSetFooBar()`. This method is then called when `$fooBar` is written
+ * > to from outside the class context.
+ *
  * @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
  * @package Basics\Traits
  */
@@ -41,17 +50,14 @@ trait Setter
      *
      * @return void
      *
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException if the property does not exist
      *
      * @internal
      */
     public function __set(string $property, mixed $value): void
     {
-        $method = 'magicSet' . ucfirst($property);
-        if (
-            property_exists(static::class, $property)
-            && method_exists(static::class, $method)
-        ) {
+        $method = '_magicSet' . ucfirst($property);
+        if (property_exists(static::class, $property) && method_exists(static::class, $method)) {
             $this->$method($value);
         } else {
             throw new InvalidArgumentException(
@@ -71,8 +77,6 @@ trait Setter
      *
      * @return void
      *
-     * @throws InvalidArgumentException
-     *
      * @internal
      */
     public function __unset(string $property): void
diff --git a/src/Traits/Singleton.php b/src/Traits/Singleton.php
index 531b7f2..3f150a3 100644
--- a/src/Traits/Singleton.php
+++ b/src/Traits/Singleton.php
@@ -80,7 +80,7 @@ trait Singleton
      *
      * @return void
      *
-     * @throws LogicException
+     * @throws LogicException if trying to clone `$this`
      *
      * @internal
      */