more optimizations and attempts at documentation