Doxygen: added warnings and details to planning_scene_monitor.h

Added warnings to PlanningSceneMonitor::getPlanningScene() functions and added a bunch of details to the docs for LockedPlanningSceneRO and RW.

@isucan especially, can you check over these comments for correctness?