document return types for type hints