diff --git a/doc/adapter-api.txt b/doc/adapter-api.txt
index 490608e..48466ab 100644
--- a/doc/adapter-api.txt
+++ b/doc/adapter-api.txt
@@ -21,6 +21,9 @@ Methods		void StartDiscovery()
 
 			During discovery RSSI delta-threshold is imposed.
 
+			Each client can request a single device discovery session
+			per adapter.
+
 			Possible errors: org.bluez.Error.NotReady
 					 org.bluez.Error.Failed
 					 org.bluez.Error.InProgress
@@ -32,7 +35,8 @@ Methods		void StartDiscovery()
 
 			Note that a discovery procedure is shared between all
 			discovery sessions thus calling StopDiscovery will only
-			release a single session.
+			release a single session and discovery will stop when
+			all sessions from all clients have finished.
 
 			Possible errors: org.bluez.Error.NotReady
 					 org.bluez.Error.Failed