Document upcoming return type changes

This is similar to PHPC-1710. Since adding return types to existing methods constitute a BC break if the class in question is extended, this change has to be done first in userland code. To allow for this change, we should document return types that will be added in 2.0 so users can prepare for that upgrade.