interface better reflects documentation now.  added example to documentation