doc, example & new methods