Javadoc improvments and clarifications.  This provides additional details and in a couple places fixes some minor details in the javadocs which were incorrect.