add code comments about the auth_hint interface

certbot/certbot/_internal/auth_handler.py

@@ -285,6 +285,8 @@ class AuthHandler(object):
         for _, achalls in sorted(problems.items(), key=lambda item: item[0]):
             msg.append(_generate_failed_chall_msg(achalls))
 
+        # auth_hint can currently only be implemented by authenticators that subclass
+        # plugin_common.Plugin. Refer to comment on that function.
         if failed_achalls and isinstance(self.auth, plugin_common.Plugin):
             msg.append('\nHint: {}\n'.format(self.auth.auth_hint(failed_achalls)))
 

certbot/certbot/plugins/common.py

@@ -106,6 +106,10 @@ class Plugin(object):
         Should describe, in simple language, what the authenticator tried to do, what went
         wrong and what the user should try as their "next steps".
 
+        TODO: auth_hint belongs in IAuthenticator but can't be added until the next major
+        version of Certbot. For now, it lives in .Plugin and auth_handler will only call it
+        on authenticators that subclass .Plugin.
+
         :param list failed_achalls: List of one or more failed challenges
                                     (:class:`achallenges.AnnotatedChallenge` subclasses).