performance improvement and a more accurate docmentation

Thanks to @boiteaweb, @startupz and @samyrabih on Twitter