ENH: improve semantics, example and internals

update what's new

COSMITS