make deprecated properties configurable. add examples
some doc fixes