Search & Reviewer Search API cleanup and documentation (bug 899232)

https://bugzilla.mozilla.org/show_bug.cgi?id=899232

I started removing `update_with_reviewer_data()` and realized we lacked tests and docs for this, so I added them while I was as it. Bonus, it fixes, or rather hides, issues people with review permissions have been having with some apps on the consumer side (see bug)