properly document arrays that are of known types to help IDEs

this is no code change, only the `@return array` have been changed to `@return XyInterface[]` where applicable to help modern IDEs recognize interfaces.