Rename "symbol" term to "element"

Author: SerafimArts

README.md

@@ -32,25 +32,25 @@ composer require type-lang/phpdoc
 
 ## Supported Tags
 
-- [x] `@abstract` - Declare any _Symbol_ as abstract
-- [x] `@api` - Highlight _Symbol_ as being part of the public API
+- [x] `@abstract` - Declare any _Element_ as abstract
+- [x] `@api` - Highlight _Element_ as being part of the public API
 - [ ] `@author` - TODO
 - [ ] `@category` - TODO
-- [x] `@copyright` - Used to document the copyright information of any _Symbol_.
+- [x] `@copyright` - Used to document the copyright information of any _Element_.
 - [ ] `@deprecated` - TODO
 - [ ] `@example` - TODO
 - [x] `@extends` - Allows to extend templated classes and interfaces
 - [ ] `@filesource` - TODO
-- [x] `@final` - Declare any _Symbol_ as final
+- [x] `@final` - Declare any _Element_ as final
 - [ ] `@global` - TODO
-- [x] `@ignore` - Used to tell documentation systems that _Symbol_ are 
+- [x] `@ignore` - Used to tell documentation systems that _Element_ are 
       not to be processed.
 - [x] `@implements` - Allows to extend templated interfaces
 - [ ] `@inheritdoc` - TODO
 - [x] `@inherits` - An alias of `@extends` tag
 - [ ] `@internal` - TODO
 - [x] `@license` - Used to indicate which license is applicable
-- [x] `@link` - Indicates a custom relation between the associated _Symbol_ 
+- [x] `@link` - Indicates a custom relation between the associated _Element_ 
       and a website, which is identified by an absolute URI
 - [x] `@method` - Allows a class to know which "_magic_" methods are callable
 - [ ] `@mixin` - TODO
@@ -90,14 +90,14 @@ composer require type-lang/phpdoc
 - [x] `@template-implements` - An alias of `@implements` tag
 - [x] `@template-use` - Allows to extend templated traits
 - [x] `@throw` - An alias of `@throws` tag
-- [x] `@throws` - Used to indicate whether _Symbol_ throw a specific type 
+- [x] `@throws` - Used to indicate whether _Element_ throw a specific type 
       of `\Throwable` (exception or error)
 - [ ] `@todo` - TODO
 - [ ] `@unused-param` - TODO
 - [x] `@use` - An alias of `@template-use` tag
 - [ ] `@used-by` - TODO
 - [ ] `@uses` - TODO
-- [x] `@var` - Document the _Type_ of the following _Symbol_
+- [x] `@var` - Document the _Type_ of the following _Element_
 - [ ] `@version` - TODO
 
 ### Psalm Tags

src/DocBlock/Tag/ApiTag/ApiTag.php

@@ -7,24 +7,24 @@
 use TypeLang\PHPDoc\DocBlock\Tag\Tag;
 
 /**
- * Used to highlight _Symbol_ as being part of the primary
+ * Used to highlight _Element_ as being part of the primary
  * public API of a package.
  *
- * The "`@api`" tag may be applied to public _Symbol_ to highlight them
+ * The "`@api`" tag may be applied to public _Element_ to highlight them
  * in generated documentation, pointing the consumer to the primary public
  * API components of a library or framework.
  *
- * When the "`@api`" tag is used, other _Symbol_ with a public
+ * When the "`@api`" tag is used, other _Element_ with a public
  * visibility serve to support the internal structure and
  * are not recommended to be used by the consumer.
  *
- * The exact meaning of _Symbol_ tagged with "`@api`" MAY differ per project.
- * It is however RECOMMENDED that all "`@api`" tagged _Symbol_ SHOULD
+ * The exact meaning of _Element_ tagged with "`@api`" MAY differ per project.
+ * It is however RECOMMENDED that all "`@api`" tagged _Element_ SHOULD
  * NOT change after publication unless the new version
  * is tagged as breaking Backwards Compatibility.
  *
  * See also the `"@internal"` tag, which can be used to hide internal
- * _Symbol_ from generated documentation.
+ * _Element_ from generated documentation.
  *
  * ```
  * "@api" [<description>]

src/DocBlock/Tag/CopyrightTag/CopyrightTag.php

@@ -7,10 +7,10 @@
 use TypeLang\PHPDoc\DocBlock\Tag\Tag;
 
 /**
- * Used to document the copyright information of any _Symbol_.
+ * Used to document the copyright information of any _Element_.
  *
- * The "`@copyright`" tag defines who holds the copyright over the _Symbol_.
- * The copyright indicated with this tag applies to the _Symbol_ with which
+ * The "`@copyright`" tag defines who holds the copyright over the _Element_.
+ * The copyright indicated with this tag applies to the _Element_ with which
  * it is associated and all child elements unless otherwise noted.
  *
  * The format of the description is governed by the coding standard of each

src/DocBlock/Tag/FinalTag/FinalTag.php

@@ -7,8 +7,8 @@
 use TypeLang\PHPDoc\DocBlock\Tag\Tag;
 
 /**
- * Used to denote that the associated _Symbol_ is final, are not allowed to
- * extend or override the _Symbol_ in a child element.
+ * Used to denote that the associated _Element_ is final, are not allowed to
+ * extend or override the _Element_ in a child element.
  *
  * In some situations the language construct final cannot be used by the
  * implementing library where the functionality of the library prevents

src/DocBlock/Tag/IgnoreTag/IgnoreTag.php

@@ -7,7 +7,7 @@
 use TypeLang\PHPDoc\DocBlock\Tag\Tag;
 
 /**
- * Used to tell documentation systems that _Symbol_ are not to be processed.
+ * Used to tell documentation systems that _Element_ are not to be processed.
  *
  * ```
  * "@ignore" [<description>]

src/DocBlock/Tag/LicenseTag/LicenseTag.php

@@ -8,10 +8,10 @@
 use TypeLang\PHPDoc\DocBlock\Tag\Tag;
 
 /**
- * Used to indicate which license is applicable for the associated _Symbol_.
+ * Used to indicate which license is applicable for the associated _Element_.
  *
  * The `"@license"` tag provides the user with the name and URL of the license
- * that is applicable to a _Symbol_ and any of its child elements.
+ * that is applicable to a _Element_ and any of its child elements.
  *
  * Whenever multiple licenses apply, there MUST be one "`@license"` tag per
  * applicable license.

src/DocBlock/Tag/LinkTag/LinkTag.php

@@ -9,7 +9,7 @@
 
 /**
  * The "`@link`" tag can be used to define a relation, or link, between
- * the symbol, or part of the long description when used inline, to a URI.
+ * the element, or part of the long description when used inline, to a URI.
  *
  * The URI MUST be complete and well-formed as specified in RFC2396.
  *

src/DocBlock/Tag/SeeTag/SeeTag.php

@@ -5,15 +5,15 @@
 namespace TypeLang\PHPDoc\DocBlock\Tag\SeeTag;
 
 use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ReferenceInterface;
-use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\SymbolReference;
+use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ElementReference;
 use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\UriReference;
 use TypeLang\PHPDoc\DocBlock\Tag\Tag;
 
 /**
- * The "`@see`" tag can be used to define a {@see SymbolReference symbol} or
+ * The "`@see`" tag can be used to define a {@see ElementReference element} or
  * to an {@see UriReference external URI}.
  *
- * When defining a reference to other symbols, you can refer to a specific
+ * When defining a reference to other elements, you can refer to a specific
  * element by appending a double colon and providing the name of that element
  * (also called the 'Fully Qualified Name' or _FQN_).
  *

src/DocBlock/Tag/SeeTag/SeeTagFactory.php

@@ -8,7 +8,7 @@
 use TypeLang\Parser\ParserInterface as TypesParserInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
 use TypeLang\PHPDoc\Parser\Content\Stream;
-use TypeLang\PHPDoc\Parser\Content\SymbolReferenceReader;
+use TypeLang\PHPDoc\Parser\Content\ElementReferenceReader;
 use TypeLang\PHPDoc\Parser\Content\UriReferenceReader;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
 
@@ -30,7 +30,7 @@ public function create(string $tag, string $content, DescriptionParserInterface
         try {
             $reference = $stream->apply(new UriReferenceReader());
         } catch (\Throwable) {
-            $reference = $stream->apply(new SymbolReferenceReader($this->parser));
+            $reference = $stream->apply(new ElementReferenceReader($this->parser));
         }
 
         return new SeeTag(

src/DocBlock/Tag/Shared/Reference/ClassConstantSymbolReference.php src/DocBlock/Tag/Shared/Reference/ClassConstantElementReference.php

@@ -9,7 +9,7 @@
 /**
  * Related to any internal class property reference
  */
-final class ClassConstantSymbolReference extends ClassSymbolReference
+final class ClassConstantElementReference extends ClassElementReference
 {
     public function __construct(
         Name $class,

src/DocBlock/Tag/Shared/Reference/ClassSymbolReference.php src/DocBlock/Tag/Shared/Reference/ClassElementReference.php

@@ -9,7 +9,7 @@
 /**
  * Related to any internal class reference
  */
-abstract class ClassSymbolReference extends SymbolReference
+abstract class ClassElementReference extends ElementReference
 {
     public function __construct(
         public readonly Name $class,

src/DocBlock/Tag/Shared/Reference/ClassMethodSymbolReference.php src/DocBlock/Tag/Shared/Reference/ClassMethodElementReference.php

@@ -9,7 +9,7 @@
 /**
  * Related to any internal class property reference
  */
-final class ClassMethodSymbolReference extends ClassSymbolReference
+final class ClassMethodElementReference extends ClassElementReference
 {
     public function __construct(
         Name $class,

src/DocBlock/Tag/Shared/Reference/ClassPropertySymbolReference.php src/DocBlock/Tag/Shared/Reference/ClassPropertyElementReference.php

@@ -9,7 +9,7 @@
 /**
  * Related to any internal class property reference
  */
-final class ClassPropertySymbolReference extends ClassSymbolReference
+final class ClassPropertyElementReference extends ClassElementReference
 {
     public function __construct(
         Name $class,

src/DocBlock/Tag/Shared/Reference/SymbolReference.php src/DocBlock/Tag/Shared/Reference/ElementReference.php

@@ -7,4 +7,4 @@
 /**
  * Related to any internal reference
  */
-abstract class SymbolReference implements ReferenceInterface {}
+abstract class ElementReference implements ReferenceInterface {}

src/DocBlock/Tag/Shared/Reference/FunctionReference.php

@@ -9,7 +9,7 @@
 /**
  * Related to internal function reference
  */
-final class FunctionReference extends SymbolReference
+final class FunctionReference extends ElementReference
 {
     public function __construct(
         public readonly Name $function,

src/DocBlock/Tag/Shared/Reference/ReferenceInterface.php

@@ -5,6 +5,6 @@
 namespace TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference;
 
 /**
- * Represents reference to the external or internal symbol
+ * Represents reference to the external or internal element
  */
 interface ReferenceInterface {}

src/DocBlock/Tag/Shared/Reference/TypeSymbolReference.php src/DocBlock/Tag/Shared/Reference/TypeElementReference.php

@@ -9,7 +9,7 @@
 /**
  * Related to internal type reference
  */
-final class TypeSymbolReference extends SymbolReference
+final class TypeElementReference extends ElementReference
 {
     public function __construct(
         public readonly TypeStatement $type,

src/DocBlock/Tag/Shared/Reference/VariableReference.php

@@ -9,7 +9,7 @@
 /**
  * Related to local variable reference
  */
-final class VariableReference extends SymbolReference
+final class VariableReference extends ElementReference
 {
     public function __construct(
         public readonly VariableLiteralNode $variable,

src/Parser/Content/SymbolReferenceReader.php src/Parser/Content/ElementReferenceReader.php

@@ -9,18 +9,18 @@
 use TypeLang\Parser\Node\Stmt\ClassConstNode;
 use TypeLang\Parser\Node\Stmt\NamedTypeNode;
 use TypeLang\Parser\ParserInterface as TypesParserInterface;
-use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ClassConstantSymbolReference;
-use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ClassMethodSymbolReference;
-use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ClassPropertySymbolReference;
+use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ClassConstantElementReference;
+use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ClassMethodElementReference;
+use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ClassPropertyElementReference;
 use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\FunctionReference;
-use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\SymbolReference;
-use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\TypeSymbolReference;
+use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ElementReference;
+use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\TypeElementReference;
 use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\VariableReference;
 
 /**
- * @template-implements ReaderInterface<SymbolReference>
+ * @template-implements ReaderInterface<ElementReference>
  */
-final class SymbolReferenceReader implements ReaderInterface
+final class ElementReferenceReader implements ReaderInterface
 {
     private OptionalTypeReader $types;
 
@@ -29,7 +29,7 @@ public function __construct(TypesParserInterface $parser)
         $this->types = new OptionalTypeReader($parser);
     }
 
-    public function __invoke(Stream $stream): SymbolReference
+    public function __invoke(Stream $stream): ElementReference
     {
         $type = ($this->types)($stream);
 
@@ -56,10 +56,10 @@ public function __invoke(Stream $stream): SymbolReference
             $identifier = $type->constant->toString();
 
             if (\str_starts_with($stream->value, '()')) {
-                return new ClassMethodSymbolReference($type->class, $identifier);
+                return new ClassMethodElementReference($type->class, $identifier);
             }
 
-            return new ClassConstantSymbolReference($type->class, $identifier);
+            return new ClassConstantElementReference($type->class, $identifier);
         }
 
         throw $stream->toException(\sprintf(
@@ -68,16 +68,16 @@ public function __invoke(Stream $stream): SymbolReference
         ));
     }
 
-    private function createFromFunction(CallableTypeNode $type): SymbolReference
+    private function createFromFunction(CallableTypeNode $type): ElementReference
     {
         if ($type->type !== null || $type->parameters->items !== []) {
-            return new TypeSymbolReference($type);
+            return new TypeElementReference($type);
         }
 
         return new FunctionReference($type->name);
     }
 
-    private function createFromNamedType(NamedTypeNode $type, Stream $stream): SymbolReference
+    private function createFromNamedType(NamedTypeNode $type, Stream $stream): ElementReference
     {
         if (\str_starts_with($stream->value, '::')) {
             if ($type->arguments === null && $type->fields === null) {
@@ -87,7 +87,7 @@ private function createFromNamedType(NamedTypeNode $type, Stream $stream): Symbo
                 $variable = $stream->apply(new OptionalVariableNameReader());
 
                 if ($variable !== null) {
-                    return new ClassPropertySymbolReference(
+                    return new ClassPropertyElementReference(
                         class: $type->name,
                         property: $variable,
                     );
@@ -100,6 +100,6 @@ class: $type->name,
             ));
         }
 
-        return new TypeSymbolReference($type);
+        return new TypeElementReference($type);
     }
 }