Closes #741

And some small javadoc polishing.

Comment From: tzolov

Nice improvements! Thank you @piotrooo !

Comment From: tzolov

rebased and merged at 06ff651734bf70dc2fcec63db9f13d4ccaa178eb