Enhance generics documentation and tests for class, interface, and trait inheritance; add single-line inline trait use example

Author: rcalicdan

docs/generics/generics-and-bounds.md

@@ -663,7 +663,7 @@ $producers->add(new Producer(new Car()));
 
 ---
 
-## Class Inheritance (`@extends`, `@implements`, and `@use`)
+## Class, Interface, & Trait Inheritance (`@extends`, `@implements`, `@use`)
 
 When a child class extends a generic parent class, implements a generic interface, or uses a generic trait, declare the template mapping using any of the recognized inherited template annotations:
 
@@ -673,6 +673,8 @@ When a child class extends a generic parent class, implements a generic interfac
 | **Interface Implementation** | `@implements`, `@template-implements`, `@phpstan-implements`, `@psalm-implements` |
 | **Trait Usage** | `@use`, `@template-use`, `@phpstan-use` |
 
+### 1. Interface Implementation (`@implements` / `@template-implements`)
+
 ```php
 /**
  * Generic Interface
@@ -711,6 +713,106 @@ $processor->process(new Dog());
 // Throws: TypeError: CatProcessor::process(): Argument $item (template T = Cat) must be of type Cat
 ```
 
+### 2. Class Extension (`@extends` / `@template-extends`)
+
+```php
+/**
+ * @template T
+ */
+abstract class BaseRepository
+{
+    /**
+     * @param T $entity
+     */
+    public function save(mixed $entity): void
+    {
+        // ...
+    }
+}
+
+/**
+ * Fulfills T = User via @template-extends
+ *
+ * @template-extends BaseRepository<User>
+ */
+class UserRepository extends BaseRepository
+{
+}
+
+$userRepo = new UserRepository();
+
+// Valid Save
+$userRepo->save(new User('Alice'));
+
+// Invalid Save
+$userRepo->save(new Product('SKU-100'));
+// Throws: TypeError: UserRepository::save(): Argument $entity (template T = User) must be of type User
+```
+
+### 3. Generic Traits (`@use` / `@template-use` / `@phpstan-use`)
+
+When a class uses a generic Trait, declare the template binding either at the **class level** or **directly above the inline `use Trait;` statement**:
+
+#### Generic Trait Definition (`ItemLoggerTrait.php`)
+
+```php
+/**
+ * @template T
+ */
+trait ItemLoggerTrait
+{
+    /**
+     * @param T $item
+     */
+    public function logItem(mixed $item): bool
+    {
+        return true;
+    }
+}
+```
+
+#### Option A: Class-Level Trait Annotation (`@use` / `@template-use`)
+
+```php
+/**
+ * Class docblock binds T = Dog for the trait
+ *
+ * @use ItemLoggerTrait<Dog>
+ */
+class ClassLevelLogService
+{
+    use ItemLoggerTrait;
+}
+
+$service = new ClassLevelLogService();
+
+$service->logItem(new Dog()); // Valid
+
+$service->logItem(new Car());
+// Throws: TypeError: Argument $item (template T = Dog) must be of type Dog, Car given
+```
+
+#### Option B: Inline Statement Trait Annotation (`/** @use */ use Trait;`)
+
+```php
+class InlineLogService
+{
+    /**
+     * Inline statement docblock binds T = Dog
+     *
+     * @use ItemLoggerTrait<Dog>
+     */
+    use ItemLoggerTrait;
+}
+
+$service = new InlineLogService();
+
+$service->logItem(new Dog()); // Valid
+
+$service->logItem(new Car());
+// Throws: TypeError: Argument $item (template T = Dog) must be of type Dog, Car given
+```
+
 ---
 
 ## Real-World Example 1: Generic Collections (`Collection<T>`)
@@ -994,3 +1096,4 @@ processCovariantConsumer(new Consumer(new Dog()));
 processCovariantConsumer(new Consumer(new Car()));
 // Throws: TypeError: processCovariantConsumer() expects Consumer<covariant Animal>, but Consumer<Car> was given
 ```
+```

tests/Fixtures/Generics/SingleLineInlineTraitUseService.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypePHP\Tests\Fixtures\Generics;
+
+use TypePHP\Tests\Fixtures\Domain\Dog;
+
+class SingleLineInlineTraitUseService
+{
+    /** @use GenericItemLoggerTrait<Dog> */
+    use GenericItemLoggerTrait;
+}

tests/TypeChecking/Generics/GenericTraitsUseAnnotationTest.php

@@ -7,6 +7,7 @@
 use TypePHP\Tests\Fixtures\Domain\Dog;
 use TypePHP\Tests\Fixtures\Generics\ClassLevelTraitService;
 use TypePHP\Tests\Fixtures\Generics\InlineTraitUseService;
+use TypePHP\Tests\Fixtures\Generics\SingleLineInlineTraitUseService;
 use TypePHP\TypePHP;
 
 describe('Generic Traits with @use, @template-use, and @phpstan-use Annotations', function () {
@@ -34,5 +35,15 @@
                 ->toThrow(TypeError::class, 'must be of type TypePHP\Tests\Fixtures\Domain\Dog')
             ;
         });
+
+        test('pre-binds generic template T with single-line docblock (/** @use Trait<T> */ use Trait;)', function () {
+            $service = new SingleLineInlineTraitUseService();
+
+            expect(TypePHP::getGenericType($service))->toBe(Dog::class);
+
+            expect($service->logItem(new Dog()))->toBeTrue();
+            expect(fn () => $service->logItem(new Car()))
+                ->toThrow(TypeError::class, 'must be of type TypePHP\Tests\Fixtures\Domain\Dog');
+        });
     });
 });