add new sample() documetation