Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

do not resolve types if it's not possible #254

Merged
merged 11 commits into from Sep 3, 2020

Conversation

voku
Copy link
Contributor

@voku voku commented Sep 1, 2020

Build errors:
https://travis-ci.org/github/JetBrains/phpstorm-stubs/builds/723069982

Pull request where I try to add "&" and "..." in the docs:
JetBrains/phpstorm-stubs#892


This change is Reviewable

@voku voku changed the title Param: do not resolve types if it's not possible do not resolve types if it's not possible Sep 1, 2020
@voku
Copy link
Contributor Author

voku commented Sep 1, 2020

@jaapio I see Exceptions like the following, since I added & and ... to phpdocs for phpstorm-stubs, maybe you have some time to review this. This PR is something like an extended version of my last fix: 443d86e

/opt/project/phpstorm-stubs/tests/StubsTest.php:350
2) StubTests\StubsTest::testMethodsPHPDocs with data set "method HttpRequest::head" ('head', StubTests\Model\PHPMethod Object (...))
RuntimeException: A type is missing before a type separator in /opt/project/phpstorm-stubs/vendor/phpdocumentor/type-resolver/src/TypeResolver.php:180
Stack trace:
#0 /opt/project/phpstorm-stubs/vendor/phpdocumentor/type-resolver/src/TypeResolver.php(155): phpDocumentor\Reflection\TypeResolver->parseTypes(Object(ArrayIterator), Object(phpDocumentor\Reflection\Types\Context), 0)
#1 /opt/project/phpstorm-stubs/vendor/phpdocumentor/reflection-docblock/src/DocBlock/Tags/Param.php(79): phpDocumentor\Reflection\TypeResolver->resolve('&$info', Object(phpDocumentor\Reflection\Types\Context))
#2 /opt/project/phpstorm-stubs/vendor/phpdocumentor/reflection-docblock/src/DocBlock/StandardTagFactory.php(216): phpDocumentor\Reflection\DocBlock\Tags\Param::create('[optional]', Object(phpDocumentor\Reflection\TypeResolver), Object(phpDocumentor\Reflection\DocBlock\DescriptionFactory), Object(phpDocumentor\Reflection\Types\Context))
#3 /opt/project/phpstorm-stubs/vendor/phpdocumentor/reflection-docblock/src/DocBlock/StandardTagFactory.php(148): phpDocumentor\Reflection\DocBlock\StandardTagFactory->createTag('&$info [optiona...', 'param', Object(phpDocumentor\Reflection\Types\Context))
#4 /opt/project/phpstorm-stubs/vendor/phpdocumentor/reflection-docblock/src/DocBlockFactory.php(244): phpDocumentor\Reflection\DocBlock\StandardTagFactory->create('@param &$info [...', Object(phpDocumentor\Reflection\Types\Context))
#5 /opt/project/phpstorm-stubs/vendor/phpdocumentor/reflection-docblock/src/DocBlockFactory.php(104): phpDocumentor\Reflection\DocBlockFactory->parseTagBlock('@param $url\n@pa...', Object(phpDocumentor\Reflection\Types\Context))
#6 /opt/project/phpstorm-stubs/tests/Model/PHPFunction.php(84): phpDocumentor\Reflection\DocBlockFactory->create('/**\n\t * @param ...')
#7 /opt/project/phpstorm-stubs/tests/Model/PHPMethod.php(53): StubTests\Model\PHPFunction->checkReturnTag(Object(PhpParser\Node\Stmt\ClassMethod))
#8 /opt/project/phpstorm-stubs/tests/Parsers/Visitors/ASTVisitor.php(70): StubTests\Model\PHPMethod->readObjectFromStubNode(Object(PhpParser\Node\Stmt\ClassMethod))
#9 /opt/project/phpstorm-stubs/vendor/nikic/php-parser/lib/PhpParser/NodeTraverser.php(200): StubTests\Parsers\Visitors\ASTVisitor->enterNode(Object(PhpParser\Node\Stmt\ClassMethod))
#10 /opt/project/phpstorm-stubs/vendor/nikic/php-parser/lib/PhpParser/NodeTraverser.php(114): PhpParser\NodeTraverser->traverseArray(Array)
#11 /opt/project/phpstorm-stubs/vendor/nikic/php-parser/lib/PhpParser/NodeTraverser.php(223): PhpParser\NodeTraverser->traverseNode(Object(PhpParser\Node\Stmt\Class_))
#12 /opt/project/phpstorm-stubs/vendor/nikic/php-parser/lib/PhpParser/NodeTraverser.php(91): PhpParser\NodeTraverser->traverseArray(Array)
#13 /opt/project/phpstorm-stubs/tests/Parsers/StubParser.php(91): PhpParser\NodeTraverser->traverse(Array)
#14 /opt/project/phpstorm-stubs/tests/Parsers/StubParser.php(33): StubTests\Parsers\StubParser::processStubs(Object(StubTests\Parsers\Visitors\ASTVisitor), Object(StubTests\Parsers\Visitors\CoreStubASTVisitor), Object(Closure))
#15 /opt/project/phpstorm-stubs/tests/TestData/Providers/PhpStormStubsSingleton.php(16): StubTests\Parsers\StubParser::getPhpStormStubs()
#16 /opt/project/phpstorm-stubs/tests/TestData/Providers/StubsTestDataProviders.php(12): StubTests\TestData\Providers\PhpStormStubsSingleton::getPhpStormStubs()
#17 /opt/project/phpstorm-stubs/vendor/phpunit/phpunit/src/Util/Annotation/DocBlock.php(436): StubTests\TestData\Providers\StubsTestDataProviders::stubClassConstantProvider()
#18 /opt/project/phpstorm-stubs/vendor/phpunit/phpunit/src/Util/Annotation/DocBlock.php(284): PHPUnit\Util\Annotation\DocBlock->getDataFromDataProviderAnnotation('/**\n     * @dat...')
#19 /opt/project/phpstorm-stubs/vendor/phpunit/phpunit/src/Util/Test.php(317): PHPUnit\Util\Annotation\DocBlock->getProvidedData()
#20 /opt/project/phpstorm-stubs/vendor/phpunit/phpunit/src/Framework/TestBuilder.php(74): PHPUnit\Util\Test::getProvidedData('StubTests\\Stubs...', 'testClassConsta...')
#21 /opt/project/phpstorm-stubs/vendor/phpunit/phpunit/src/Framework/TestSuite.php(889): PHPUnit\Framework\TestBuilder->build(Object(ReflectionClass), 'testClassConsta...')
#22 /opt/project/phpstorm-stubs/vendor/phpunit/phpunit/src/Framework/TestSuite.php(231): PHPUnit\Framework\TestSuite->addTestMethod(Object(ReflectionClass), Object(ReflectionMethod))
#23 /opt/project/phpstorm-stubs/vendor/phpunit/phpunit/src/Framework/TestSuite.php(361): PHPUnit\Framework\TestSuite->__construct(Object(ReflectionClass))
#24 /opt/project/phpstorm-stubs/vendor/phpunit/phpunit/src/Framework/TestSuite.php(500): PHPUnit\Framework\TestSuite->addTestSuite(Object(ReflectionClass))
#25 /opt/project/phpstorm-stubs/vendor/phpunit/phpunit/src/Framework/TestSuite.php(525): PHPUnit\Framework\TestSuite->addTestFile('/opt/project/ph...')
#26 /opt/project/phpstorm-stubs/vendor/phpunit/phpunit/src/Runner/BaseTestRunner.php(98): PHPUnit\Framework\TestSuite->addTestFiles(Array)
#27 /opt/project/phpstorm-stubs/vendor/phpunit/phpunit/src/TextUI/Command.php(124): PHPUnit\Runner\BaseTestRunner->getTest('/opt/project/ph...', Array)
#28 /opt/project/phpstorm-stubs/vendor/phpunit/phpunit/src/TextUI/Command.php(100): PHPUnit\TextUI\Command->run(Array, true)
#29 /opt/project/phpstorm-stubs/vendor/phpunit/phpunit/phpunit(61): PHPUnit\TextUI\Command::main()
#30 {main}

Copy link
Member

@jaapio jaapio left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@voku thanks a lot for this PR.

A lot has been changed. So it is kind of hard to see if we are not breaking anything, which could result in incoming issues. This code is kind of highly sensitive because it is used in so many projects. I want to be careful with large PR's.

Besides that, I'm not sure if any other tag rather then @param should have support for variadic and reference. I never used variadic properties? Unless I'm incorrect and you can show me some examples of variadic properties I would like to stick with the original behavior for the other tags.

If you discovered a bug in the original patch, a fix is more than welcome.

@voku
Copy link
Contributor Author

voku commented Sep 2, 2020

@jaapio 👍 you are right, I only saw the code that looks ~ the same in all this classes, but I reverted it. And here is only the fix for my current problem.

@jaapio
Copy link
Member

jaapio commented Sep 2, 2020

Could you please add a test-case which reproduces the issue you had?

@voku
Copy link
Contributor Author

voku commented Sep 2, 2020

@jaapio I added some more tests ...

... but in the tests I also saw a new issue where $myVariable My Description was converted into $myVariable Description, so I fixed that also.

@jaapio
Copy link
Member

jaapio commented Sep 2, 2020

Thanks, when I have a quick look at the changes this looks good to me.

I'm going to do another review soon. But I think we can merge this as is 👍

@voku
Copy link
Contributor Author

voku commented Sep 3, 2020

@jaapio By adding more unit tests I saw more strange test results. :-/ I don't know if I should revert everything back to the fix for my current problem, without the tests and extra fixes? What do you think?

@jaapio
Copy link
Member

jaapio commented Sep 3, 2020

Thanks for adding all these test. With just quick look, it seems you are fixing some nice output issues here.

for any future contributions I would like you to ask to split the PR into multiple smaller PR's. Which makes the review easier, but also allows us to merge things separate. So we can move faster :-)

Thanks a lot for all the effort you are spending on this. I will try to review your changes as soon as possible. Unless something is wrong I will handle some changes that I would write in a different way.

if ($some != '' ) { 
    $var = $some;
} else {
  $var = '';
}

return $var;

Could also be written as:

if ($some != '' ) { 
    return $some;
} 

return '';

Which makes it a bit more readable IMO.

@jaapio jaapio merged commit 069a785 into phpDocumentor:master Sep 3, 2020
@GrahamCampbell
Copy link
Contributor

isn't that the same as return (string) $some;?

@voku
Copy link
Contributor Author

voku commented Sep 3, 2020

@GrahamCampbell @jaapio

isn't that the same as return (string) $some;?

The code mostly looks like this:

        if ($this->description) {
            $description = $this->description->render();
        } else {
            $description = '';
        }

        $variableName = '';
        if ($this->variableName) {
            $variableName .= ($this->isReference ? '&' : '') . ($this->isVariadic ? '...' : '');
            $variableName .= '$' . $this->variableName;
        }

        $type = (string) $this->type;

        return $type
            . ($variableName !== '' ? ($type !== '' ? ' ' : '') . $variableName : '')
            . ($description !== '' ? ($type !== '' || $variableName !== '' ? ' ' : '') . $description : '');

Maybe the next example would be more clean, but with more function calls. I don't know if performance is relevant here?

        $return = [];
        $return[] = $this->type ? $this->type->__toString() : '';
        $return[] = $this->variableName ? ($this->isReference ? '&' : '') . ($this->isVariadic ? '...' : '') . '$' . $this->variableName : '';
        $return[] = $this->description ? $this->description->render() : '';

        return implode(' ', array_filter($return, fn($v) => ($v !== '')));    

@jaapio
Copy link
Member

jaapio commented Sep 4, 2020

My example was a simplified version.
Performance is definitely a thing in this lib, but I'm not sure if it is for the toString methods... I do never use them

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants