added spec javadocs and applied some minor polishing.