Squiz / FunctionComment: fix detection of incorrect types when @return tag has description

[jrfnl]

Also incidentally fixes a "Function return type is not void, but function has no return statement" error being thrown when it shouldn't be when using multiple types including void, i.e. array|void.

Includes unit tests specific to this issue in a separate file + fixed file.

Fixes #1018

Note: the unit tests are in a separate file as the "main" unit test file for this sniff does not have a .fixed version and adding that is currently not an option as there are a number of other bugs in the sniff.
Once all the bugs are solved & a .fixed file for the main unit test file can be added, the tests for this issue can be added to the main file.

[jrfnl]

FYI: I'm preparing follow up PRs for several of the other fixer bugs in this sniff, but will pull them one by one to prevent continuous merge conflicts. Or I could add them as separate commits to this PR if you prefer that.

[fabacino]

Looking forward to this fix :)

[gsherwood]

Thanks for this PR. It worked great.

I ended up merging the unit tests into the main file and adding a .fixed file for it. There were only a couple of bugs exposed, which I fixed in this commit: 4079d5f

[jrfnl]

@gsherwood thanks for merging & fixing this. I did already have the fixes ready & waiting though, which could have saved you some work (see comment above) ;-)
I'll run a check to see if all the things I found have been addressed and if anything is still left over from my original fixes, I'll send you a separate PR.

[gsherwood]

I'll run a check to see if all the things I found have been addressed and if anything is still left over from my original fixes, I'll send you a separate PR.

:) thanks