update examples to new API
comment & document source code like a responsible contributor
Revert "update examples to new API" as i did this on the wrong branch

This reverts commit 88b581e41537ab0807dd6816da0ade213e7592d5.