Update balanceOf function documentation

[red-swan]

Description

Clarify behavior of balanceOf function regarding token existence and execution. Currently it only describes returning zero if the token called does not exist but that is misleading for developers because it will also return zero if the address reverts during its execution or if the address returns less than 32 bytes. This PR adds those to the description of the function.

Checklist

Ensure you completed all of the steps below before submitting your pull request:

• Ran forge fmt?
• Ran forge test?

Pull requests with an incomplete checklist will be thrown out.

[Schereo]

Long term, the best option would be to rename the function. When SafeTransferLib is imported via the using SafeTransferLib for address syntax, the call looks very similar to the standard ERC-20 balanceOf() function. The only visible difference is that the function is called on an address variable rather than on an IERC20 interface, which can be easy to overlook in larger contracts.

But agree in the short term this comment is a good addition.

[red-swan]

@Schereo , I'm johnny-come-lately here. Without any evidence to support my gut here, I thought the whole idea with SafeTransferLib was to have an optimized version of the Solmate SafeTransferLib but maybe weaken some assumptions here and there to achieve it. If parity with that interface is the goal, I think you're stuck with the names they choose, no?

[Schereo]

@red-swan Without knowing the full reasoning behind the naming, I do not think it is related to Solmate's interface. The latest Solmate SafeTransferLib does not include a balanceOf() function: https://github.com/transmissions11/solmate/blob/main/src/utils/SafeTransferLib.sol