fix(docs): keep @example tags when a method is seen through several traits (#289)

Assisted-by: Claude Code:Opus-5

Co-authored-by: Marilena Ruffelaere <marilena.ruffelaere@sensiolabs.com>

Author: marilenaRM

docs/generate.php

@@ -361,6 +361,10 @@ private function prepareBuilderFromClass(ReflectionClass $class): void
                     $parsedDocBlock['tags']['see'],
                 )));
             }
+
+            if (isset($parsedDocBlock['tags']['example']) && [] !== $parsedDocBlock['tags']['example']) {
+                $this->parts['methods']['@'][$method->getShortName()]['tags']['example'] = $parsedDocBlock['tags']['example'];
+            }
         }
     }
 

docs/pdf/HtmlPdfBuilder.md

@@ -509,6 +509,15 @@ Adds a file, like an image, font, stylesheet, and so on.<br /><br />By default,
 > [!TIP]
 > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets)
 
+```php
+return $gotenberg
+    // Your builder call as ->html() and the rest of your configuration code
+    ->addAsset('../img/ceo.jpeg')
+    ->generate()
+    ->stream()
+;
+```
+
 ### assets(Stringable|string ...\$paths)
 Adds additional files, like images, fonts, stylesheets, and so on (overrides any previous files).<br /><br />By default, the assets files are fetch in the assets folder of your application.<br />If your assets are in another folder, you can override the default value of assets_directory in your<br />configuration file config/sensiolabs_gotenberg.yml.<br />
 
@@ -518,7 +527,7 @@ Adds additional files, like images, fonts, stylesheets, and so on (overrides any
 ```php
 return $gotenberg
     // Your builder call as ->html() and the rest of your configuration code
-    ->assets('../img/ceo.jpeg', __DIR__'/../../public/admin.jpeg')
+    ->assets('../img/ceo.jpeg', __DIR__.'/../../public/admin.jpeg')
     ->generate()
     ->stream()
 ;

docs/pdf/MarkdownPdfBuilder.md

@@ -573,6 +573,15 @@ Adds a file, like an image, font, stylesheet, and so on.<br /><br />By default,
 > [!TIP]
 > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets)
 
+```php
+return $gotenberg
+    // Your builder call as ->html() and the rest of your configuration code
+    ->addAsset('../img/ceo.jpeg')
+    ->generate()
+    ->stream()
+;
+```
+
 ### assets(Stringable|string ...\$paths)
 Adds additional files, like images, fonts, stylesheets, and so on (overrides any previous files).<br /><br />By default, the assets files are fetch in the assets folder of your application.<br />If your assets are in another folder, you can override the default value of assets_directory in your<br />configuration file config/sensiolabs_gotenberg.yml.<br />
 
@@ -582,7 +591,7 @@ Adds additional files, like images, fonts, stylesheets, and so on (overrides any
 ```php
 return $gotenberg
     // Your builder call as ->html() and the rest of your configuration code
-    ->assets('../img/ceo.jpeg', __DIR__'/../../public/admin.jpeg')
+    ->assets('../img/ceo.jpeg', __DIR__.'/../../public/admin.jpeg')
     ->generate()
     ->stream()
 ;

docs/pdf/UrlPdfBuilder.md

@@ -506,6 +506,15 @@ Adds a file, like an image, font, stylesheet, and so on.<br /><br />By default,
 > [!TIP]
 > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets)
 
+```php
+return $gotenberg
+    // Your builder call as ->html() and the rest of your configuration code
+    ->addAsset('../img/ceo.jpeg')
+    ->generate()
+    ->stream()
+;
+```
+
 ### assets(Stringable|string ...\$paths)
 Adds additional files, like images, fonts, stylesheets, and so on (overrides any previous files).<br /><br />By default, the assets files are fetch in the assets folder of your application.<br />If your assets are in another folder, you can override the default value of assets_directory in your<br />configuration file config/sensiolabs_gotenberg.yml.<br />
 
@@ -515,7 +524,7 @@ Adds additional files, like images, fonts, stylesheets, and so on (overrides any
 ```php
 return $gotenberg
     // Your builder call as ->html() and the rest of your configuration code
-    ->assets('../img/ceo.jpeg', __DIR__'/../../public/admin.jpeg')
+    ->assets('../img/ceo.jpeg', __DIR__.'/../../public/admin.jpeg')
     ->generate()
     ->stream()
 ;

docs/screenshot/HtmlScreenshotBuilder.md

@@ -151,6 +151,15 @@ Adds a file, like an image, font, stylesheet, and so on.<br /><br />By default,
 > [!TIP]
 > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets)
 
+```php
+return $gotenberg
+    // Your builder call as ->html() and the rest of your configuration code
+    ->addAsset('../img/ceo.jpeg')
+    ->generate()
+    ->stream()
+;
+```
+
 ### assets(Stringable|string ...\$paths)
 Adds additional files, like images, fonts, stylesheets, and so on (overrides any previous files).<br /><br />By default, the assets files are fetch in the assets folder of your application.<br />If your assets are in another folder, you can override the default value of assets_directory in your<br />configuration file config/sensiolabs_gotenberg.yml.<br />
 
@@ -160,7 +169,7 @@ Adds additional files, like images, fonts, stylesheets, and so on (overrides any
 ```php
 return $gotenberg
     // Your builder call as ->html() and the rest of your configuration code
-    ->assets('../img/ceo.jpeg', __DIR__'/../../public/admin.jpeg')
+    ->assets('../img/ceo.jpeg', __DIR__.'/../../public/admin.jpeg')
     ->generate()
     ->stream()
 ;

docs/screenshot/MarkdownScreenshotBuilder.md

@@ -240,6 +240,15 @@ Adds a file, like an image, font, stylesheet, and so on.<br /><br />By default,
 > [!TIP]
 > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets)
 
+```php
+return $gotenberg
+    // Your builder call as ->html() and the rest of your configuration code
+    ->addAsset('../img/ceo.jpeg')
+    ->generate()
+    ->stream()
+;
+```
+
 ### assets(Stringable|string ...\$paths)
 Adds additional files, like images, fonts, stylesheets, and so on (overrides any previous files).<br /><br />By default, the assets files are fetch in the assets folder of your application.<br />If your assets are in another folder, you can override the default value of assets_directory in your<br />configuration file config/sensiolabs_gotenberg.yml.<br />
 
@@ -249,7 +258,7 @@ Adds additional files, like images, fonts, stylesheets, and so on (overrides any
 ```php
 return $gotenberg
     // Your builder call as ->html() and the rest of your configuration code
-    ->assets('../img/ceo.jpeg', __DIR__'/../../public/admin.jpeg')
+    ->assets('../img/ceo.jpeg', __DIR__.'/../../public/admin.jpeg')
     ->generate()
     ->stream()
 ;

docs/screenshot/UrlScreenshotBuilder.md

@@ -166,6 +166,15 @@ Adds a file, like an image, font, stylesheet, and so on.<br /><br />By default,
 > [!TIP]
 > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets)
 
+```php
+return $gotenberg
+    // Your builder call as ->html() and the rest of your configuration code
+    ->addAsset('../img/ceo.jpeg')
+    ->generate()
+    ->stream()
+;
+```
+
 ### assets(Stringable|string ...\$paths)
 Adds additional files, like images, fonts, stylesheets, and so on (overrides any previous files).<br /><br />By default, the assets files are fetch in the assets folder of your application.<br />If your assets are in another folder, you can override the default value of assets_directory in your<br />configuration file config/sensiolabs_gotenberg.yml.<br />
 
@@ -175,7 +184,7 @@ Adds additional files, like images, fonts, stylesheets, and so on (overrides any
 ```php
 return $gotenberg
     // Your builder call as ->html() and the rest of your configuration code
-    ->assets('../img/ceo.jpeg', __DIR__'/../../public/admin.jpeg')
+    ->assets('../img/ceo.jpeg', __DIR__.'/../../public/admin.jpeg')
     ->generate()
     ->stream()
 ;

src/Builder/Behaviors/Chromium/AssetTrait.php

@@ -25,7 +25,7 @@ abstract protected function getBodyBag(): BodyBag;
      *
      * @see https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets
      *
-     * @example assets('../img/ceo.jpeg', __DIR__'/../../public/admin.jpeg')
+     * @example assets('../img/ceo.jpeg', __DIR__.'/../../public/admin.jpeg')
      */
     public function assets(string|\Stringable ...$paths): static
     {
@@ -49,7 +49,7 @@ public function assets(string|\Stringable ...$paths): static
      *
      * @see https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets
      *
-     * @example addAsset('../img/ceo.jpeg', __DIR__'/../../public/admin.jpeg')
+     * @example addAsset('../img/ceo.jpeg')
      */
     public function addAsset(string|\Stringable $path): static
     {