PhpDocs update

composer.json

@@ -20,6 +20,7 @@
     ],
     "require": {
         "php": ">=7.3",
+        "ext-json": "*",
         "nesk/rialto": "^1.2.0",
         "psr/log": "^1.0",
         "vierbergenlars/php-semver": "^3.0.2"
@@ -42,7 +43,8 @@
     },
     "scripts": {
         "post-install-cmd": "npm install",
-        "test": "./vendor/bin/phpunit"
+        "test": "./vendor/bin/phpunit",
+        "update-docs": "php bin/console doc:generate"
     },
     "config": {
         "sort-packages": true

phpstan.neon

@@ -0,0 +1,9 @@
+parameters:
+    level: max
+    paths:
+        - src
+    fileExtensions:
+        - php
+    parallel:
+        maximumNumberOfProcesses: 4
+    tipsOfTheDay: false

src/Command/GenerateDocumentationCommand.php

@@ -17,6 +17,9 @@ final class GenerateDocumentationCommand extends Command
     private const NODE_MODULES_DIR = __DIR__.'/../../node_modules';
     private const RESOURCES_DIR = __DIR__.'/../Resources';
     private const RESOURCES_NAMESPACE = 'Nesk\\Puphpeteer\\Resources';
+    private const DOC_FORMAT_PHP = 'php';
+    private const DOC_FORMAT_PHPSTAN = 'phpstan';
+    private const DOC_FORMATS = [self::DOC_FORMAT_PHP, self::DOC_FORMAT_PHPSTAN];
 
     protected static $defaultName = 'doc:generate';
 
@@ -36,6 +39,7 @@ protected function configure(): void
      */
     private static function buildDocumentationGenerator(): void
     {
+        self::rmdirRecursive(self::BUILD_DIR);
         $process = new Process([
             self::NODE_MODULES_DIR.'/.bin/tsc',
             '--outDir',
@@ -55,23 +59,35 @@ private static function getDocumentation(string $puppeteerPath, array $resourceN
         $commonFiles = \glob("$puppeteerPath/lib/esm/puppeteer/common/*.d.ts");
         $nodeFiles = \glob("$puppeteerPath/lib/esm/puppeteer/node/*.d.ts");
 
-        $process = new Process(
-            \array_merge(
-                ['node', self::BUILD_DIR.'/'.self::DOC_FILE_NAME.'.js', 'php'],
-                $commonFiles,
-                $nodeFiles,
-                ['--resources-namespace', self::RESOURCES_NAMESPACE, '--resources'],
-                $resourceNames
-            )
-        );
-        $process->mustRun();
+        $result = [];
+        foreach(self::DOC_FORMATS as $format) {
+            $process = new Process(
+                \array_merge(
+                    ['node', self::BUILD_DIR.'/'.self::DOC_FILE_NAME.'.js', $format],
+                    $commonFiles,
+                    $nodeFiles,
+                    ['--resources-namespace', self::RESOURCES_NAMESPACE, '--resources'],
+                    $resourceNames
+                )
+            );
+            $process->mustRun();
+
+            foreach (\json_decode($process->getOutput(), true) as &$class) {
+                $result[$class['name']]['name'] = $class['name'];
+                $result[$class['name']][$format] = [
+                    'properties' => $class['properties'],
+                    'getters' => $class['getters'],
+                    'methods' => $class['methods'],
+                ];
+            }
+        }
 
-        return \json_decode($process->getOutput(), true);
+        return $result;
     }
 
     private static function getResourceNames(): array
     {
-        return array_map(function (string $filePath): string {
+        return array_map(static function (string $filePath): string {
             return explode('.', \basename($filePath))[0];
         }, \glob(self::RESOURCES_DIR.'/*'));
     }
@@ -80,18 +96,23 @@ private static function generatePhpDocWithDocumentation(array $classDocumentatio
     {
         $properties = array_map(function (string $property): string {
             return "\n * @property $property";
-        }, $classDocumentation['properties']);
+        }, $classDocumentation[self::DOC_FORMAT_PHP]['properties']);
         $properties = \implode('', $properties);
 
         $getters = array_map(function (string $getter): string {
             return "\n * @property-read $getter";
-        }, $classDocumentation['getters']);
+        }, $classDocumentation[self::DOC_FORMAT_PHP]['getters']);
         $getters = \implode('', $getters);
 
-        $methods = array_map(function (string $method): string {
-            return "\n * @method $method";
-        }, $classDocumentation['methods']);
-        $methods = \implode('', $methods);
+        $methods = '';
+        foreach ($classDocumentation[self::DOC_FORMAT_PHP]['methods'] as $pos => $method) {
+            $methods .= "\n * @method $method";
+
+            $phpStanMethod = $classDocumentation[self::DOC_FORMAT_PHPSTAN]['methods'][$pos];
+            //phpStorm works incorrectly if @phpstan-method is used.
+            //Using non-standard method-extended phpDoc:
+            $methods .= "\n * @method-extended $phpStanMethod";
+        }
 
         if (\strlen($properties) > 0 || \strlen($getters) > 0 || \strlen($methods) > 0) {
             return "/**$properties$getters$methods\n */";
@@ -155,7 +176,8 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         }
 
         // Handle the specific Puppeteer class
-        $classDocumentation = $documentation['Puppeteer'] ?? null;
+        $classDocumentation = array_replace_recursive($documentation['Puppeteer'], $documentation['PuppeteerNode']);
+        unset($documentation['Puppeteer'], $documentation['PuppeteerNode']);
         if ($classDocumentation !== null) {
             $phpDoc = self::generatePhpDocWithDocumentation($classDocumentation);
             if ($phpDoc !== null) {
@@ -175,4 +197,16 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
         return 0;
     }
+
+    private static function rmdirRecursive(string $dir): bool {
+        $files = scandir($dir);
+        if (!is_array($files)) {
+            return false;
+        }
+        $files = array_diff($files, array('.','..'));
+        foreach ($files as $file) {
+            (is_dir("$dir/$file")) ? self::rmdirRecursive("$dir/$file") : unlink("$dir/$file");
+        }
+        return rmdir($dir);
+    }
 }

src/Puppeteer.php

@@ -2,6 +2,8 @@
 
 namespace Nesk\Puphpeteer;
 
+use Nesk\Puphpeteer\Resources\Browser;
+use Nesk\Puphpeteer\Resources\BrowserFetcher;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\Process\Process;
 use Nesk\Rialto\AbstractEntryPoint;
@@ -10,11 +12,25 @@
 /**
  * @property-read mixed devices
  * @property-read mixed errors
- * @method \Nesk\Puphpeteer\Resources\Browser connect(array<string, mixed> $options)
+ * @property-read string product
+ * @method \Nesk\Puphpeteer\Resources\Browser connect(array $options)
+ * @method-extended \Nesk\Puphpeteer\Resources\Browser connect(array<string, mixed> $options)
  * @method void registerCustomQueryHandler(string $name, mixed $queryHandler)
+ * @method-extended void registerCustomQueryHandler(string $name, mixed $queryHandler)
  * @method void unregisterCustomQueryHandler(string $name)
+ * @method-extended void unregisterCustomQueryHandler(string $name)
  * @method string[] customQueryHandlerNames()
+ * @method-extended string[] customQueryHandlerNames()
  * @method void clearCustomQueryHandlers()
+ * @method-extended void clearCustomQueryHandlers()
+ * @method \Nesk\Puphpeteer\Resources\Browser launch(array $options = [])
+ * @method-extended \Nesk\Puphpeteer\Resources\Browser launch(array<string, mixed>&array{ product: mixed, extraPrefsFirefox: array|string[]|mixed[] } $options = null)
+ * @method string executablePath()
+ * @method-extended string executablePath()
+ * @method string[] defaultArgs(array $options = [])
+ * @method-extended string[] defaultArgs(array<string, mixed> $options = null)
+ * @method \Nesk\Puphpeteer\Resources\BrowserFetcher createBrowserFetcher(array $options)
+ * @method-extended \Nesk\Puphpeteer\Resources\BrowserFetcher createBrowserFetcher(array<string, mixed> $options)
  */
 class Puppeteer extends AbstractEntryPoint
 {

src/Resources/Accessibility.php

@@ -5,7 +5,8 @@
 use Nesk\Rialto\Data\BasicResource;
 
 /**
- * @method mixed snapshot(array<string, mixed> $options = null)
+ * @method mixed snapshot(array $options = [])
+ * @method-extended mixed snapshot(array<string, mixed> $options = null)
  */
 class Accessibility extends BasicResource
 {

src/Resources/Browser.php

@@ -4,20 +4,35 @@
 
 /**
  * @method mixed|null process()
+ * @method-extended mixed|null process()
  * @method \Nesk\Puphpeteer\Resources\BrowserContext createIncognitoBrowserContext()
+ * @method-extended \Nesk\Puphpeteer\Resources\BrowserContext createIncognitoBrowserContext()
  * @method \Nesk\Puphpeteer\Resources\BrowserContext[] browserContexts()
+ * @method-extended \Nesk\Puphpeteer\Resources\BrowserContext[] browserContexts()
  * @method \Nesk\Puphpeteer\Resources\BrowserContext defaultBrowserContext()
+ * @method-extended \Nesk\Puphpeteer\Resources\BrowserContext defaultBrowserContext()
  * @method string wsEndpoint()
+ * @method-extended string wsEndpoint()
  * @method \Nesk\Puphpeteer\Resources\Page newPage()
+ * @method-extended \Nesk\Puphpeteer\Resources\Page newPage()
  * @method \Nesk\Puphpeteer\Resources\Target[] targets()
+ * @method-extended \Nesk\Puphpeteer\Resources\Target[] targets()
  * @method \Nesk\Puphpeteer\Resources\Target target()
- * @method \Nesk\Puphpeteer\Resources\Target waitForTarget(callable(\Nesk\Puphpeteer\Resources\Target $x): bool $predicate, array<string, mixed> $options = null)
+ * @method-extended \Nesk\Puphpeteer\Resources\Target target()
+ * @method \Nesk\Puphpeteer\Resources\Target waitForTarget(\Nesk\Rialto\Data\JsFunction $predicate, array $options = [])
+ * @method-extended \Nesk\Puphpeteer\Resources\Target waitForTarget(callable(\Nesk\Puphpeteer\Resources\Target $x): bool|\Nesk\Rialto\Data\JsFunction $predicate, array<string, mixed> $options = null)
  * @method \Nesk\Puphpeteer\Resources\Page[] pages()
+ * @method-extended \Nesk\Puphpeteer\Resources\Page[] pages()
  * @method string version()
+ * @method-extended string version()
  * @method string userAgent()
+ * @method-extended string userAgent()
  * @method void close()
+ * @method-extended void close()
  * @method void disconnect()
+ * @method-extended void disconnect()
  * @method bool isConnected()
+ * @method-extended bool isConnected()
  */
 class Browser extends EventEmitter
 {

src/Resources/BrowserContext.php

@@ -4,14 +4,23 @@
 
 /**
  * @method \Nesk\Puphpeteer\Resources\Target[] targets()
- * @method \Nesk\Puphpeteer\Resources\Target waitForTarget(callable(\Nesk\Puphpeteer\Resources\Target $x): bool $predicate, array{ timeout: float } $options = null)
+ * @method-extended \Nesk\Puphpeteer\Resources\Target[] targets()
+ * @method \Nesk\Puphpeteer\Resources\Target waitForTarget(\Nesk\Rialto\Data\JsFunction $predicate, array $options = [])
+ * @method-extended \Nesk\Puphpeteer\Resources\Target waitForTarget(callable(\Nesk\Puphpeteer\Resources\Target $x): bool|\Nesk\Rialto\Data\JsFunction $predicate, array{ timeout: float } $options = null)
  * @method \Nesk\Puphpeteer\Resources\Page[] pages()
+ * @method-extended \Nesk\Puphpeteer\Resources\Page[] pages()
  * @method bool isIncognito()
+ * @method-extended bool isIncognito()
  * @method void overridePermissions(string $origin, string[] $permissions)
+ * @method-extended void overridePermissions(string $origin, string[] $permissions)
  * @method void clearPermissionOverrides()
+ * @method-extended void clearPermissionOverrides()
  * @method \Nesk\Puphpeteer\Resources\Page newPage()
+ * @method-extended \Nesk\Puphpeteer\Resources\Page newPage()
  * @method \Nesk\Puphpeteer\Resources\Browser browser()
+ * @method-extended \Nesk\Puphpeteer\Resources\Browser browser()
  * @method void close()
+ * @method-extended void close()
  */
 class BrowserContext extends EventEmitter
 {

src/Resources/BrowserFetcher.php

@@ -6,13 +6,21 @@
 
 /**
  * @method mixed platform()
+ * @method-extended mixed platform()
  * @method mixed product()
+ * @method-extended mixed product()
  * @method string host()
+ * @method-extended string host()
  * @method bool canDownload(string $revision)
- * @method mixed download(string $revision, callable(float $x, float $y): void $progressCallback = null)
+ * @method-extended bool canDownload(string $revision)
+ * @method mixed download(string $revision, \Nesk\Rialto\Data\JsFunction $progressCallback = null)
+ * @method-extended mixed download(string $revision, callable(float $x, float $y): void|\Nesk\Rialto\Data\JsFunction $progressCallback = null)
  * @method string[] localRevisions()
+ * @method-extended string[] localRevisions()
  * @method void remove(string $revision)
+ * @method-extended void remove(string $revision)
  * @method mixed revisionInfo(string $revision)
+ * @method-extended mixed revisionInfo(string $revision)
  */
 class BrowserFetcher extends BasicResource
 {

src/Resources/CDPSession.php

@@ -4,7 +4,9 @@
 
 /**
  * @method mixed send(mixed $method, mixed ...$paramArgs)
+ * @method-extended mixed send(mixed $method, mixed ...$paramArgs)
  * @method void detach()
+ * @method-extended void detach()
  */
 class CDPSession extends EventEmitter
 {

src/Resources/ConsoleMessage.php

@@ -6,10 +6,15 @@
 
 /**
  * @method mixed type()
+ * @method-extended mixed type()
  * @method string text()
+ * @method-extended string text()
  * @method \Nesk\Puphpeteer\Resources\JSHandle[] args()
+ * @method-extended \Nesk\Puphpeteer\Resources\JSHandle[] args()
  * @method mixed location()
+ * @method-extended mixed location()
  * @method mixed[] stackTrace()
+ * @method-extended mixed[] stackTrace()
  */
 class ConsoleMessage extends BasicResource
 {

src/Resources/Coverage.php

@@ -5,10 +5,14 @@
 use Nesk\Rialto\Data\BasicResource;
 
 /**
- * @method void startJSCoverage(array<string, mixed> $options = null)
+ * @method void startJSCoverage(array $options = [])
+ * @method-extended void startJSCoverage(array<string, mixed> $options = null)
  * @method mixed[] stopJSCoverage()
- * @method void startCSSCoverage(array<string, mixed> $options = null)
+ * @method-extended mixed[] stopJSCoverage()
+ * @method void startCSSCoverage(array $options = [])
+ * @method-extended void startCSSCoverage(array<string, mixed> $options = null)
  * @method mixed[] stopCSSCoverage()
+ * @method-extended mixed[] stopCSSCoverage()
  */
 class Coverage extends BasicResource
 {

src/Resources/Dialog.php

@@ -6,10 +6,15 @@
 
 /**
  * @method mixed type()
+ * @method-extended mixed type()
  * @method string message()
+ * @method-extended string message()
  * @method string defaultValue()
+ * @method-extended string defaultValue()
  * @method void accept(string $promptText = null)
+ * @method-extended void accept(string $promptText = null)
  * @method void dismiss()
+ * @method-extended void dismiss()
  */
 class Dialog extends BasicResource
 {

src/Resources/ElementHandle.php

@@ -6,20 +6,34 @@
 use Nesk\Puphpeteer\Traits\AliasesEvaluationMethods;
 
 /**
- * @method \Nesk\Puphpeteer\Resources\ElementHandle<mixed>|null asElement()
+ * @method \Nesk\Puphpeteer\Resources\ElementHandle|mixed[]|null asElement()
+ * @method-extended \Nesk\Puphpeteer\Resources\ElementHandle|mixed[]|null asElement()
  * @method \Nesk\Puphpeteer\Resources\Frame|null contentFrame()
+ * @method-extended \Nesk\Puphpeteer\Resources\Frame|null contentFrame()
  * @method void hover()
- * @method void click(array<string, mixed> $options = null)
+ * @method-extended void hover()
+ * @method void click(array $options = [])
+ * @method-extended void click(array<string, mixed> $options = null)
  * @method string[] select(string ...$values)
+ * @method-extended string[] select(string ...$values)
  * @method void uploadFile(string ...$filePaths)
+ * @method-extended void uploadFile(string ...$filePaths)
  * @method void tap()
+ * @method-extended void tap()
  * @method void focus()
- * @method void type(string $text, array{ delay: float } $options = null)
- * @method void press(mixed $key, array<string, mixed> $options = null)
+ * @method-extended void focus()
+ * @method void type(string $text, array $options = [])
+ * @method-extended void type(string $text, array{ delay: float } $options = null)
+ * @method void press(mixed $key, array $options = [])
+ * @method-extended void press(mixed $key, array<string, mixed> $options = null)
  * @method mixed|null boundingBox()
+ * @method-extended mixed|null boundingBox()
  * @method mixed|null boxModel()
- * @method string|mixed|null screenshot(array{  } $options = null)
+ * @method-extended mixed|null boxModel()
+ * @method string|mixed|null screenshot(array $options = [])
+ * @method-extended string|mixed|null screenshot(array{  } $options = null)
  * @method bool isIntersectingViewport()
+ * @method-extended bool isIntersectingViewport()
  */
 class ElementHandle extends JSHandle
 {