began documentations design
small condition optimizations in various functions