(#1045) clarify javadocs to accurately describe currently-intended behavior of sample()