added depreciation warning to module doc-string

tweaked examples