performance improvements & updated docs
classified some //TODO as //PERFORMANCE/ALLOCATION