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

[Copilot]

Summary

This PR adds comprehensive documentation to the gix-url::Url struct explaining:

1. Why there is no String serialization (no Into<String> or From<Url> for String implementation)
2. How passwords are handled during serialization, particularly with the serde feature

Changes

Added a new Serialization section to the Url struct documentation that clarifies:

String Serialization

The type does not implement Into<String> or From<Url> for String because URLs can contain non-UTF-8 sequences in the path component. Users should instead:

• Use to_bstring() for lossless serialization to BString
• Use the Display trait for a UTF-8 representation that redacts passwords for safe logging

Password Handling

• When the serde feature is enabled, serde::Serialize and serde::Deserialize will serialize all fields including passwords
• Passwords are never serialized through the Display trait or in any other context unless the serde feature is explicitly enabled and serde serialization is used

This documentation helps users understand the security implications of different serialization methods and choose the appropriate one for their use case.

Example

use gix_url::Url;

let url: Url = "https://user:password@example.com/repo.git".try_into()?;

// Display trait redacts password (safe for logging)
println!("{}", url); // https://user:redacted@example.com/repo.git

// to_bstring() includes password (lossless)
let serialized = url.to_bstring(); // https://user:password@example.com/repo.git

// serde serialization (when feature enabled) also includes password

Fixes the documentation gap identified in the issue.

Original prompt

Point out why gix-url::Url doesn't have a String serialisation in the struct documentation. Also mention that the password is never serialised unless the serde feature is enabled.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.