diff --git a/src/lib.rs b/src/lib.rs
index f60f76e81..e5ea55bba 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1952,11 +1952,19 @@ impl Url {
 
     /// Change this URL’s scheme.
     ///
-    /// Do nothing and return `Err` if:
+    /// Do nothing and return `Err` under the following circumstances:
     ///
-    /// * The new scheme is not in `[a-zA-Z][a-zA-Z0-9+.-]+`
-    /// * This URL is cannot-be-a-base and the new scheme is one of
+    /// * If the new scheme is not in `[a-zA-Z][a-zA-Z0-9+.-]+`
+    /// * If this URL is cannot-be-a-base and the new scheme is one of
     ///   `http`, `https`, `ws`, `wss`, `ftp`, or `gopher`
+    /// * If either the old or new scheme is `http`, `https`, `ws`,
+    ///   `wss`, `ftp`, or `gopher` and the other is not one of these
+    /// * If the new scheme is `file` and this URL includes credentials
+    ///   or has a non-null port
+    /// * If this URL's scheme is `file` and its host is empty or null
+    ///
+    /// See also [the URL specification's section on legal scheme state
+    /// overrides](https://url.spec.whatwg.org/#scheme-state).
     ///
     /// # Examples
     ///