> And finally - you got two pieces of JavaDoc in here and the important info that makes this different is outside the main javadoc.

I wished to leave the original javadoc unchanged since those semantics of use are unchanged. You'll also note the second batch is non-javadoc comments.