clarify docstrings
explicitly mention array (Object) return values in README