PM: refactor - add to docs and update tests