new javadocs plus some minor changes