add some javadocs at Radu's request