added return values where useful & fixed some inline docs