When I look at the PHP core documentation I see when a parameter is a reference or not. (so we should review all our function documentation)
For example if you look at:
Not only I know the type but also when it is a reference it is mentionned as &$array
I think we should do the same in our documentation, when I see our API with cas, for example:
it is not clear to me.