PM / OPP: Update kernel documentation

kernel doc has gotten bit-rotted over time. Re-sync with Locking and
Return information. document all functions properly and ensure that
./scripts/kernel-doc -v  ./drivers/base/power/opp.c >/dev/null returns
no errors

Signed-off-by: Nishanth Menon <nm@ti.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
(cherry picked from commit 984f16c8490cba715444124a453ed4a2ac7a5a54)
Signed-off-by: Alex Shi <alex.shi@linaro.org>