Add more Javadoc and some minor API changes

* some internal redesign for better performance