updated docs/samples to use upcoming API