clarify return values in docs (closes #43)