adding some comments, updated the docs, and deprecate the pb stop event