api: clarify return values in documentation