docs update; examples improvements