some doc and optimizations