add support for clear_cache and segments

 - also emphaize params in documentation