Bluetooth: Doc: Improve docs in bluetooth.h

Adds improvements to the API docs in bluetooth.h, with the aim of
making the API less ambiguous and more informative.

Signed-off-by: Håvard Reierstad <[email protected]>

Author: HaavardRei