Merge pull request #2223 from GitoxideLabs/copilot/update-gix-url-documentation

Document why `gix-url::Url` doesn't have String serialization and password handling behavior

Author: Byron

gix-url/src/lib.rs

@@ -76,7 +76,7 @@ pub enum ArgumentSafety<'a> {
 
 /// A URL with support for specialized git related capabilities.
 ///
-/// Additionally there is support for [deserialization](Url::from_bytes()) and [serialization](Url::to_bstring()).
+/// Additionally, there is support for [deserialization](Url::from_bytes()) and [serialization](Url::to_bstring()).
 ///
 /// # Mutability Warning
 ///
@@ -85,6 +85,16 @@ pub enum ArgumentSafety<'a> {
 /// parameters, but never be accepted as an instance of this type and then reconstructed, to maintain
 /// validity guarantees.
 ///
+/// # Serialization
+///
+/// This type does not implement `Into<String>`, `From<Url> for String` because URLs
+/// can contain non-UTF-8 sequences in the path component when parsed from raw bytes.
+/// Use [to_bstring()](Url::to_bstring()) for lossless serialization, or use the [`Display`](std::fmt::Display)
+/// trait for a UTF-8 representation that redacts passwords for safe logging.
+///
+/// When the `serde` feature is enabled, this type implements `serde::Serialize` and `serde::Deserialize`,
+/// which will serialize *all* fields, including the password.
+///
 /// # Security Warning
 ///
 /// URLs may contain passwords and using standard [formatting](std::fmt::Display) will redact