more documentation and propagating to the examples