Fixup docstrings

synapse/handlers/identity.py

@@ -150,14 +150,16 @@ class IdentityHandler(BaseHandler):
 
         Args:
             mxid (str): Matrix user ID of binding to be removed
-            threepid (dict): Dict with medium & address of binding to be removed
+            threepid (dict): Dict with medium & address of binding to be
+                removed, and an optional id_server.
 
         Raises:
             SynapseError: If we failed to contact the identity server
 
         Returns:
             Deferred[bool]: True on success, otherwise False if the identity
-            server doesn't support unbinding
+            server doesn't support unbinding (or no identity server found to
+            contact).
         """
         if threepid.get("id_server"):
             id_servers = [threepid["id_server"]]

synapse/storage/registration.py

@@ -358,9 +358,9 @@ class RegistrationWorkerStore(SQLBaseStore):
         )
 
     def remove_user_bound_threepid(self, user_id, medium, address, id_server):
-        """The server proxied a bind request to the given identity server on
-        behalf of the given user. We need to remember this in case the user
-        asks us to unbind the threepid.
+        """The server proxied an unbind request to the given identity server on
+        behalf of the given user, so we remove the mapping of threepid to
+        identity server.
 
         Args:
             user_id (str)

synapse/storage/schema/delta/53/user_threepid_id.sql

@@ -13,8 +13,8 @@
  * limitations under the License.
  */
 
--- Tracks when
-CREATE TABlE user_threepid_id_server (
+-- Tracks which identity server a user bound their threepid via.
+CREATE TABLE user_threepid_id_server (
     user_id TEXT NOT NULL,
     medium TEXT NOT NULL,
     address TEXT NOT NULL,