More semantic docs

Change-Id: Ia968058c6f22198d88ba21bad23ebd1c66782b01
Reviewed-on: http://review.couchbase.org/25764
Reviewed-by: Volker Mische <volker.mische@gmail.com>
Tested-by: Volker Mische <volker.mische@gmail.com>