Added the README update to master separately: e96473d and forcepushed this branch. I'm gonna start review, it's possible I'll divide it more again :)

Also feel free to check out the commits I added. The main reason why I changed the tests is that checking out types inside the method (through PhpFunctionFromParserNodeReflection) and checking the types outside the method (getting the return type from Reflection) are two different code paths - see that NodeScopeResolver::getPhpDocs is called in itself (for PhpFunctionFromParserNodeReflection), and in PhpClassReflectionExtension (for outsiders).

This is "a good thing" (TM) - thanks.
Now we are getting error reports where the parent interface declares some @return, but the class that implements the interface does not actually return anything. In particular it found places where the interface had:

	 * @return null

and the implementation has no return statement at all.

Probably in that case the interface should just have:

	 * @return void

And that keeps phpstan happy that the implementation has no return statement at all.

Otherwise at the end of the method implementation I have to add:

return null;

which seems a crappy thing to do.

This is expected - void and null and interchangeable as values in PHP (void method returns null) but not types, so PHPStan does the right thing here - implementation should follow interface.

@alexeyinkin @ondrejmirtes I think there is something wrong with throws tag.

When writing

class A {
  /** @throws \LogicException */
  public method foo()
  {
    throw \LogicException();
  }
}

class B extends A {
  public method foo()
  {
    return;
  }
}

Since B::foo has no @throws tag, it uses the @throw tag of A::foo.
Phpstan then believe it's

class B extends A {
  /** @throws \LogicException */
  public method foo()
  {
    return;
  }
}

This is a big issue for https://packagist.org/packages/pepakriz/phpstan-exception-rules users.
Because phpstan will report an unused exception for B::foo or will ask for using try/catch when using B::foo.

This is expected. See phpstan/phpstan#3350