add documentation, change return value name