Add struct and type doc comments for extra::url::*

Updated doc comments further, following suggestions from huonw in PR
#10752.

1 files changed, 20 insertions, 6 deletions

diff --git a/src/libextra/url.rs b/src/libextra/url.rs
index 034d7e110fb..4190bd9036b 100644
--- a/src/libextra/url.rs
+++ b/src/libextra/url.rs
@@ -22,21 +22,35 @@ use std::uint;
 /// A Uniform Resource Locator (URL).  A URL is a form of URI (Uniform Resource
 /// Identifier) that includes network location information, such as hostname or
 /// port number.
+///
+/// # Example
+///
+/// ```rust
+/// let url = Url { scheme: ~"https",
+///                 user: Some(UserInfo { user: ~"username", pass: None }),
+///                 host: ~"example.com",
+///                 port: Some(~"8080"),
+///                 path: ~"/foo/bar",
+///                 query: ~[(~"baz", ~"qux")],
+///                 fragment: Some(~"quz") };
+/// // https://username@example.com:8080/foo/bar?baz=qux#quz
+/// ```
 #[deriving(Clone, Eq)]
 pub struct Url {
-    /// The scheme part of a URL, such as `http`, `ftp` or `mailto`.
+    /// The scheme part of a URL, such as `https` in the above example.
     scheme: ~str,
-    /// A URL subcomponent for user authentication.
+    /// A URL subcomponent for user authentication.  `username` in the above example.
     user: Option<UserInfo>,
-    /// A domain name or IP address.  For example, `www.example.com`.
+    /// A domain name or IP address.  For example, `example.com`.
     host: ~str,
     /// A TCP port number, for example `8080`.
     port: Option<~str>,
-    /// The path component of a URL, for example `/users/jsmith`.
+    /// The path component of a URL, for example `/foo/bar`.
     path: ~str,
-    /// The query component of a URL.
+    /// The query component of a URL.  `~[(~"baz", ~"qux")]` represents the
+    /// fragment `baz=qux` in the above example.
     query: Query,
-    /// The fragment component.  Does not include the leading hash or pound sign.
+    /// The fragment component, such as `quz`.  Doesn't include the leading `#` character.
     fragment: Option<~str>
 }