Update TransactionGateway.php

[719media]

The braintree php library is fairly frustrating to use from a typehint/phpdoc standpoint.
The phpdocs are often times just plain wrong.

Just some examples of bad phpdoc:
Not using @throws, putting the @throws into the return (crazy lol), classes in @returns that don't ever get returned, classes missing in @returns...

If the method could throw many/multiple things, I left as @throws Exception as a generic, but if desired you could go deeper.

I'm not sure in braintree is working on a new version that will supersede all of this, so I don't want to take the time to audit everything, but I at least wanted to call it to your attention and see what thoughts you had.

Thanks.

[hollabaq86]

👋 @719media thanks for the PR. For historical context on phpdoc being... not ideal, please see my comment in this issue. We'll take a look at your changes and get them merged in.

For internal tracking, ticket 2237

[719media]

Yes, the PR here is just a small sample, there are other problems in this same TransactionGateway class, and many more problems exist in other classes as well.

I don't know what PHP versions you are trying to support, but you could always remove the php 7.3/7.4 support (which PHP themselves have stopped supporting: see https://www.php.net/supported-versions.php), and then you'll have access to union type returns, which will greatly simplify the complexity of tying typedoc documentation together with actual return types (although it would be good practice to still typedoc the @throws).