Rename "symbol" term to "element"

Kirill Nesmeyanov · Kirill Nesmeyanov · commit bc647b4f27d6 · 2025-03-11T03:24:11.000+03:00
diff --git a/README.md b/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
diff --git a/src/DocBlock/Tag/ApiTag/ApiTag.php b/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>]
diff --git a/src/DocBlock/Tag/CopyrightTag/CopyrightTag.php b/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
diff --git a/src/DocBlock/Tag/FinalTag/FinalTag.php b/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
diff --git a/src/DocBlock/Tag/IgnoreTag/IgnoreTag.php b/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>]
diff --git a/src/DocBlock/Tag/LicenseTag/LicenseTag.php b/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.
diff --git a/src/DocBlock/Tag/LinkTag/LinkTag.php b/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.
  *
diff --git a/src/DocBlock/Tag/SeeTag/SeeTag.php b/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_).
  *
diff --git a/src/DocBlock/Tag/SeeTag/SeeTagFactory.php b/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(
diff --git a/src/DocBlock/Tag/Shared/Reference/ClassConstantElementReference.php b/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,
diff --git a/src/DocBlock/Tag/Shared/Reference/ClassElementReference.php b/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,
diff --git a/src/DocBlock/Tag/Shared/Reference/ClassMethodElementReference.php b/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,
diff --git a/src/DocBlock/Tag/Shared/Reference/ClassPropertyElementReference.php b/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,
diff --git a/src/DocBlock/Tag/Shared/Reference/ElementReference.php b/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 {}
diff --git a/src/DocBlock/Tag/Shared/Reference/FunctionReference.php b/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,
diff --git a/src/DocBlock/Tag/Shared/Reference/ReferenceInterface.php b/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 {}
diff --git a/src/DocBlock/Tag/Shared/Reference/TypeElementReference.php b/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,
diff --git a/src/DocBlock/Tag/Shared/Reference/VariableReference.php b/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,
diff --git a/src/Parser/Content/ElementReferenceReader.php b/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);
     }
 }

Original file line number	Diff line number	Diff line change
`@@ -7,10 +7,10 @@`
`7`	`7`	`use TypeLang\PHPDoc\DocBlock\Tag\Tag;`
`8`	`8`
`9`	`9`	`/**`
`10`		`- * Used to document the copyright information of any _Symbol_.`
	`10`	`+ * Used to document the copyright information of any _Element_.`
`11`	`11`	`*`
`12`		- * The "`@copyright`" tag defines who holds the copyright over the _Symbol_.
`13`		`- * The copyright indicated with this tag applies to the _Symbol_ with which`
	`12`	+ * The "`@copyright`" tag defines who holds the copyright over the _Element_.
	`13`	`+ * The copyright indicated with this tag applies to the _Element_ with which`
`14`	`14`	`* it is associated and all child elements unless otherwise noted.`
`15`	`15`	`*`
`16`	`16`	`* The format of the description is governed by the coding standard of each`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@`
`7`	`7`	`use TypeLang\PHPDoc\DocBlock\Tag\Tag;`
`8`	`8`
`9`	`9`	`/**`
`10`		`- * Used to tell documentation systems that _Symbol_ are not to be processed.`
	`10`	`+ * Used to tell documentation systems that _Element_ are not to be processed.`
`11`	`11`	`*`
`12`	`12`	* ```
`13`	`13`	`* "@ignore" [<description>]`
Original file line number	Diff line number	Diff line change
`@@ -8,10 +8,10 @@`
`8`	`8`	`use TypeLang\PHPDoc\DocBlock\Tag\Tag;`
`9`	`9`
`10`	`10`	`/**`
`11`		`- * Used to indicate which license is applicable for the associated _Symbol_.`
	`11`	`+ * Used to indicate which license is applicable for the associated _Element_.`
`12`	`12`	`*`
`13`	`13`	* The `"@license"` tag provides the user with the name and URL of the license
`14`		`- * that is applicable to a _Symbol_ and any of its child elements.`
	`14`	`+ * that is applicable to a _Element_ and any of its child elements.`
`15`	`15`	`*`
`16`	`16`	* Whenever multiple licenses apply, there MUST be one "`@license"` tag per
`17`	`17`	`* applicable license.`
Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@`
`9`	`9`
`10`	`10`	`/**`
`11`	`11`	* The "`@link`" tag can be used to define a relation, or link, between
`12`		`- * the symbol, or part of the long description when used inline, to a URI.`
	`12`	`+ * the element, or part of the long description when used inline, to a URI.`
`13`	`13`	`*`
`14`	`14`	`* The URI MUST be complete and well-formed as specified in RFC2396.`
`15`	`15`	`*`