clarify delete-invalid-user messages and docstrings

jupyterhub/app.py

@@ -956,14 +956,16 @@ class JupyterHub(Application):
             except Exception:
                 self.log.exception("Error adding user %r already in db", user.name)
                 if self.authenticator.delete_invalid_users:
-                    self.log.warning("Deleting invalid user %r", user.name)
+                    self.log.warning("Deleting invalid user %r from the Hub database", user.name)
                     db.delete(user)
                 else:
                     self.log.warning(dedent("""
                     You can set
                         c.Authenticator.delete_invalid_users = True
-                    to automatically delete users that have been invalidated,
+                    to automatically delete users from the Hub database that no longer pass
-                    e.g. by deleting them from the external system without notifying JupyterHub.
+                    Authenticator validation,
+                    such as when user accounts are deleted from the external system
+                    without notifying JupyterHub.
                     """))
         db.commit()
 

jupyterhub/auth.py

@@ -126,11 +126,19 @@ class Authenticator(LoggingConfigurable):
     ).tag(config=True)
 
     delete_invalid_users = Bool(False,
-        help="""Delete any invalid users from the database
+        help="""Delete any users from the database that do not pass validation
 
-        When JupyterHub starts, if any users are found in the database
+        When JupyterHub starts, `.add_user` will be called
-        that do not pass a `validate_users` check, they will be deleted.
+        on each user in the database to verify that all users are still valid.
-        Default is False to avoid data loss due to config changes, etc.
+
+        If `delete_invalid_users` is True,
+        any users that do not pass validation will be deleted from the database.
+        Use this if users might be deleted from an external system,
+        such as local user accounts.
+
+        If False (default), invalid users remain in the Hub's database
+        and a warning will be issued.
+        This is the default to avoid data loss due to config changes.
         """
     )