Ticket #35065: docblocks.2.diff

tests/phpunit/tests/docs/docblocks.php

@@ +1 @@
+<?php
+
+require_once dirname( dirname( dirname( __FILE__ ) ) ) . '/vendor/autoload.php';
+
+class Tests_DocBlocks extends WP_UnitTestCase {
+
+        protected static $ignore_empty  = true;
+        protected static $method_refs   = array();
+        protected static $function_refs = array();
+
+        public function remove_variadic_params( $param_doc ) {
+                return ( false === strpos( $param_doc, ',...' ) );
+        }
+
+        /**
+         * Test a function or method for a given class
+         *
+         * @dataProvider dataReflectionTestFunctions
+         *
+         * @param string|array $function The function name, or array of class name and method name.
+         * @param string       $file     The file name.
+         */
+        public function testFunctionDocBlock( $function, $filename ) {
+
+                if ( is_array( $function ) ) {
+                        $name = $function[0] . '::' . $function[1] . '()';
+                        $ref  = self::$method_refs[ $filename ][ $function[0] ][ $name ];
+                } else {
+                        $name = $function;
+                        $ref  = self::$function_refs[ $filename ][ $name ];
+                }
+
+                $name     = ltrim( $name, '\\' );
+                $docblock = $ref->getDocblock();
+
+                if ( self::$ignore_empty && empty( $docblock ) ) {
+                        return;
+                }
+
+                $this->assertNotEmpty( $docblock, sprintf(
+                        'The docblock for `%s` should not be missing.',
+                        $name
+                ) );
+
+                $method_params = $ref->getArguments();
+                $doc_params    = $docblock->getTagsByName( 'param' );
+                $desc          = $docblock->getDescription();
+
+                if ( self::$ignore_empty && empty( $desc ) ) {
+                        return;
+                }
+
+                $this->assertNotEmpty( $desc, sprintf(
+                        'The docblock description for `%s` should not be empty.',
+                        $name
+                ) );
+
+                if ( count( $method_params ) < count( $doc_params ) ) {
+                        $non_variadic_doc_params = array_filter( $doc_params, array( $this, 'remove_variadic_params' ) );
+                } else {
+                        $non_variadic_doc_params = $doc_params;
+                }
+
+                $this->assertSame( count( $method_params ), count( $non_variadic_doc_params ), sprintf(
+                        'The number of @param docs for `%s` should match its number of parameters.',
+                        $name
+                ) );
+
+                foreach ( $method_params as $i => $param ) {
+
+                        $param_doc   = $doc_params[ $i ];
+                        $description = (string) $param_doc->getDescription();
+                        $is_hash     = ( ( 0 === strpos( $description, '{' ) ) && ( ( strlen( $description ) - 1 ) === strrpos( $description, '}' ) ) );
+
+                        if ( $is_hash ) {
+                                $lines = explode( "\n", $description );
+                                $description = $lines[1];
+                        }
+
+                        if ( self::$ignore_empty && empty( $description ) ) {
+                                return;
+                        }
+
+                        $this->assertNotEmpty( $description, sprintf(
+                                'The @param description for the `$%s` parameter of `%s` should not be empty.',
+                                $param_doc->getVariableName(),
+                                $name
+                        ) );
+
+                        $param_doc_name = $param_doc->getVariableName();
+                        $param_doc_type = (string) $param_doc->getType();
+
+                        $this->assertSame( $param->getName(), $param_doc_name, sprintf(
+                                'The @param name for the `%s` parameter of `%s` is incorrect.',
+                                $param->getName(),
+                                $name
+                        ) );
+
+                        // if ( $param->isOptional() ) {
+                        //      $this->assertNotFalse( strpos( $description, 'Optional' ), sprintf(
+                        //              'The @param description for the optional `%s` parameter of `%s` should state that it is optional.',
+                        //              $param_doc_name,
+                        //              $name
+                        //      ) );
+                        // } else {
+                        //      $this->assertFalse( strpos( $description, 'Optional.' ), sprintf(
+                        //              'The @param description for the required `%s` parameter of `%s` should not state that it is optional.',
+                        //              $param_doc_name,
+                        //              $name
+                        //      ) );
+                        // }
+
+                        // if ( $param->isDefaultValueAvailable() ) {
+                        //      $this->assertNotFalse( strpos( $description, 'Default ' ), sprintf(
+                        //              'The @param description for the `%s` parameter of `%s` should state its default value.',
+                        //              $param_doc_name,
+                        //              $name
+                        //      ) );
+                        // } else {
+                        //      $this->assertFalse( strpos( $description, 'Default ' ), sprintf(
+                        //              'The @param description for the `%s` parameter of `%s` should not state a default value.',
+                        //              $param_doc_name,
+                        //              $name
+                        //      ) );
+                        // }
+
+                }
+
+        }
+
+        protected static function rsearch( $folder, $ext ) {
+                $iterator = new RecursiveIteratorIterator( new RecursiveDirectoryIterator( $folder ) );
+
+                $files = array(); 
+
+                foreach ( $iterator as $file ) {
+
+                        if ( $file->isDir() ) { 
+                                continue;
+                        }
+                        if ( $ext !== $file->getExtension() ) {
+                                continue;
+                        }
+
+                        $files[] = $file->getPathname(); 
+
+                }
+                return $files;
+        }
+
+        public function dataReflectionTestFunctions() {
+
+                $to_search = ABSPATH . 'wp-includes/';
+
+                // Recursive:
+                $files = self::rsearch( $to_search, 'php' );
+
+                // Non-recursive
+                // $files = glob( $to_search . '*.php' );
+
+                $ignore_files = array(
+
+                        ABSPATH . 'wp-admin/includes/class-pclzip.php',
+                        ABSPATH . 'wp-admin/includes/class-ftp.php',
+                        ABSPATH . 'wp-admin/includes/class-ftp-pure.php',
+                        ABSPATH . 'wp-admin/includes/class-ftp-sockets.php',
+                        ABSPATH . 'wp-admin/includes/export.php',
+                        ABSPATH . 'wp-admin/includes/file.php',
+
+                        ABSPATH . 'wp-includes/class-IXR.php',
+                        ABSPATH . 'wp-includes/rss.php',
+
+                );
+                $files = array_diff( $files, $ignore_files );
+                $files = array_filter( $files, function( $file ) {
+
+                        $ignore_dirs = array(
+                                ABSPATH . 'wp-includes/ID3/',
+                                ABSPATH . 'wp-includes/SimplePie/',
+                                ABSPATH . 'wp-includes/Text/',
+                        );
+
+                        foreach ( $ignore_dirs as $dir ) {
+                                if ( 0 === strpos( $file, $dir ) ) {
+                                        return false;
+                                }
+                        }
+                        return true;
+
+                } );
+                $data  = array();
+
+                $projectFactory = \phpDocumentor\Reflection\Php\ProjectFactory::createInstance();
+
+                foreach ( $files as $project_file ) {
+                        try {
+                                $project = $projectFactory->create( 'WordPress', array( $project_file ) );
+                        } catch ( InvalidArgumentException $e ) {
+                                // This catches files where functions are defined within functions.
+                                // eg. redirect_canonical()::lowercase_octets() in wp-includes/canonical.php
+                                continue;
+                        }
+
+                        foreach ( $project->getFiles() as $filename => $file ) {
+
+                                foreach ( $file->getFunctions() as $f => $func_ref ) {
+
+                                        self::$function_refs[ $filename ][ $f ] = $func_ref;
+
+                                        $data[] = array(
+                                                (string) $func_ref->getFqsen(),
+                                                $filename,
+                                        );
+
+                                }
+
+                                foreach ( $file->getClasses() as $c => $class_ref ) {
+
+                                        foreach ( $class_ref->getMethods() as $m => $method_ref ) {
+
+                                                self::$method_refs[ $filename ][ $c ][ $m ] = $method_ref;
+
+                                                $data[] = array(
+                                                        array(
+                                                                (string) $class_ref->getFqsen(),
+                                                                $method_ref->getName(),
+                                                        ),
+                                                        $filename,
+                                                );
+
+                                        }
+
+                                }
+
+                        }
+
+                }
+
+                return $data;
+
+        }
+
+}

tests/phpunit/composer.json

@@ +1 @@
+{
+    "name": "wordpress/tests",
+    "description": "Tests!",
+    "require": {
+        "phpdocumentor/reflection": "~2.0"
+    }
+}