updated javadoc and added a test case that peter wanted put back in.