doc for return values, updated todos