doc: Expand description of various Hangup cases

1 files changed, 16 insertions, 7 deletions

diff --git a/doc/voicecall-api.txt b/doc/voicecall-api.txt
index 8db47efd..78960a13 100644
--- a/doc/voicecall-api.txt
+++ b/doc/voicecall-api.txt
@@ -39,13 +39,22 @@ Methods		dict GetProperties()
 			condition.  This is generally implemented using CHLD=0.
 
 			Please note that the GSM specification does not allow
-			the release of a held call when a waiting call exists,
-			or the release of a particular party in a held
-			multiparty call.
-
-			Note that releasing a held call or a particular party
-			of a held multiparty call might not be possible on some
-			implementations.
+			the release of a held call when a waiting call exists.
+			This is because 27.007 allows CHLD=1X to operate only
+			on active calls.  Hence a held call cannot be hung up
+			without affecting the state of the incoming call (e.g.
+			using other CHLD alternatives). Most manufacturers
+			provide vendor extensions that do allow the state of
+			the held call to be modified using CHLD=1X or
+			equivalent.  It should be noted that Bluetooth HFP
+			specifies the classic 27.007 behavior and does not
+			allow CHLD=1X to modify the state of held calls.
+
+			Based on the discussion above, it should also be noted
+			that releasing a particular party of a held multiparty
+			call might not be possible on some implementations.
+			It is recommended for the applications to structure
+			their UI accordingly.
 
 			NOTE: Releasing active calls does not produce
 			side-effects.  That is the state of held or waiting