update examples, doc, and return types