merge and some improved return values and PHPdocs