Echo_bot: Add documentation for expect_problems

Signed-off-by: Maxime “pep” Buquet <pep@bouah.net>

examples/echo_client.py

@@ -173,7 +173,7 @@ class EchoBot(ClientXMPP):
                 # `recipients` parameter that requires for a list of JIDs,
                 # allows you to encrypt for 1:1 as well as groupchats (MUC).
                 #
-                # TODO: Document expect_problems
+                # `expect_problems`: See EncryptionPrepareException handling.
                 recipients = [mto]
                 encrypt = await self['xep_0384'].encrypt_message(body, recipients, expect_problems)
                 msg.append(encrypt)
@@ -186,9 +186,20 @@ class EchoBot(ClientXMPP):
                 self['xep_0384'].trust(exn.bare_jid, exn.device, exn.ik)
             # TODO: catch NoEligibleDevicesException
             except EncryptionPrepareException as exn:
+                # This exception is being raised when the library has tried
+                # all it could and doesn't know what to do anymore. It
+                # contains a list of exceptions that the user must resolve, or
+                # explicitely ignore via `expect_problems`.
                 # TODO: We might need to bail out here if errors are the same?
                 for error in exn.errors:
                     if isinstance(error, MissingBundleException):
+                        # We choose to ignore MissingBundleException. It seems
+                        # to be somewhat accepted that it's better not to
+                        # encrypt for a device if it has problems and encrypt
+                        # for the rest, rather than error out. The "faulty"
+                        # device won't be able to decrypt and should display a
+                        # generic message. The receiving end-user at this
+                        # point can bring up the issue if it happens.
                         self.plain_reply(
                             original_msg,
                             'Could not find keys for device "%d" of recipient "%s". Skipping.' %