fully flesh-out documentation, with examples