add missing returns, phpdoc and change some types