doc: Expand description of various Hangup cases

diff --git a/doc/voicecall-api.txt b/doc/voicecall-api.txt
index 8db47ef..78960a1 100644 (file)
--- 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