Update docs and removed useless files too

Author: mvriel

docs/expressions.rst

@@ -0,0 +1,26 @@
+Expressions
+===========
+
+Starting with version 5.4, we now support parsing expressions and extracting types and references to elements from them.
+
+.. info::
+
+   An expression is, for example, the default value for a property or argument, the definition of an enum case or a
+   constant value. These are called expressions and can contain more complex combinations of operators and values.
+
+As this library revolves around reflecting Static information, most parts of an expression are considered irrelevant;
+except for type information -such as type hints- and references to other elements, such as constants. As such, whenever
+an expression is interpreted, it will result in a string containing placeholders and an array containing the reflected
+parts -such as FQSENs-.
+
+This means that the getters like ``getDefault()`` will return a string or when you provide the optional argument
+$isString as being false, it will return an Expression object; which, when cast to string, will provide the same result.
+
+.. warning::
+
+   Deprecation: In version 6, we will remove the optional argument and always return an Expression object. When the
+   result was used as a string nothing will change, but code that checks if the output is a string will no longer
+   function starting from that version.
+
+This will allow consumers to be able to extract types and links to elements from expressions. This allows consumers to,
+for example, interpret the default value for a constructor promoted properties when it directly instantiates an object.

docs/index.rst

@@ -25,4 +25,5 @@ are however several advantages to using this library:
 
    getting-started
    reflection-structure
+   expressions
    extending/index

src/phpDocumentor/Reflection/Php/Argument.php

@@ -16,6 +16,11 @@
 use phpDocumentor\Reflection\Type;
 use phpDocumentor\Reflection\Types\Mixed_;
 
+use function is_string;
+use function trigger_error;
+
+use const E_USER_DEPRECATED;
+
 /**
  * Descriptor representing a single Argument of a method or function.
  *

src/phpDocumentor/Reflection/Php/Constant.php

@@ -20,6 +20,11 @@
 use phpDocumentor\Reflection\Location;
 use phpDocumentor\Reflection\Metadata\MetaDataContainer as MetaDataContainerInterface;
 
+use function is_string;
+use function trigger_error;
+
+use const E_USER_DEPRECATED;
+
 /**
  * Descriptor representing a constant
  *

src/phpDocumentor/Reflection/Php/EnumCase.php

@@ -11,6 +11,11 @@
 use phpDocumentor\Reflection\Location;
 use phpDocumentor\Reflection\Metadata\MetaDataContainer as MetaDataContainerInterface;
 
+use function is_string;
+use function trigger_error;
+
+use const E_USER_DEPRECATED;
+
 /**
  * Represents a case in an Enum.
  *

src/phpDocumentor/Reflection/Php/Expression.php

@@ -7,6 +7,10 @@
 use phpDocumentor\Reflection\Fqsen;
 use phpDocumentor\Reflection\Type;
 
+use function array_keys;
+use function array_map;
+use function str_replace;
+
 final class Expression
 {
     private string $expression;
@@ -33,7 +37,7 @@ public function getParts(): array
     public function __toString(): string
     {
         $valuesAsStrings = array_map(
-            static fn(object $part): string => (string)$part,
+            static fn (object $part): string => (string) $part,
             $this->parts
         );
 

src/phpDocumentor/Reflection/Php/Expression/ExpressionPrinter.php

@@ -8,11 +8,11 @@
 use PhpParser\Node\Name;
 use PhpParser\PrettyPrinter\Standard;
 
+use function md5;
+
 final class ExpressionPrinter extends Standard
 {
-    /**
-     * @var array<Fqsen>
-     */
+    /** @var array<Fqsen> */
     private array $parts = [];
 
     protected function resetState(): void

src/phpDocumentor/Reflection/Php/Factory/ClassConstant.php

@@ -30,6 +30,8 @@
 use PhpParser\PrettyPrinter\Standard as PrettyPrinter;
 use Webmozart\Assert\Assert;
 
+use function is_string;
+
 /**
  * Strategy to convert ClassConstantIterator to ConstantElement
  *
@@ -113,6 +115,7 @@ private function determineValue(ClassConstantIterator $value): null|Expression
         if ($this->valueConverter instanceof ExpressionPrinter) {
             $expression = new Expression($expression, $this->valueConverter->getParts());
         }
+
         if (is_string($expression)) {
             $expression = new Expression($expression, []);
         }

src/phpDocumentor/Reflection/Php/Factory/Define.php

@@ -33,6 +33,7 @@
 use PhpParser\PrettyPrinter\Standard as PrettyPrinter;
 
 use function assert;
+use function is_string;
 use function sprintf;
 use function str_starts_with;
 
@@ -130,6 +131,7 @@ private function determineValue(Arg|null $value): ValueExpression|null
         if ($this->valueConverter instanceof ExpressionPrinter) {
             $expression = new ValueExpression($expression, $this->valueConverter->getParts());
         }
+
         if (is_string($expression)) {
             $expression = new ValueExpression($expression, []);
         }

src/phpDocumentor/Reflection/Php/Factory/GlobalConstant.php

@@ -25,6 +25,8 @@
 use PhpParser\PrettyPrinter\Standard as PrettyPrinter;
 use Webmozart\Assert\Assert;
 
+use function is_string;
+
 /**
  * Strategy to convert GlobalConstantIterator to ConstantElement
  *
@@ -88,6 +90,7 @@ private function determineValue(GlobalConstantIterator $value): ?Expression
         if ($this->valueConverter instanceof ExpressionPrinter) {
             $expression = new Expression($expression, $this->valueConverter->getParts());
         }
+
         if (is_string($expression)) {
             $expression = new Expression($expression, []);
         }