From 0515e0541f6fed6e1b50d1b558ffe45625cd4a35 Mon Sep 17 00:00:00 2001 From: Dave Hodder Date: Sun, 1 Dec 2013 12:30:32 +0000 Subject: [PATCH 1/2] Add struct and type doc comments for extra::url::* --- src/libextra/url.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/libextra/url.rs b/src/libextra/url.rs index cfa4680052d0b..034d7e110fbfe 100644 --- a/src/libextra/url.rs +++ b/src/libextra/url.rs @@ -19,23 +19,37 @@ use std::hashmap::HashMap; use std::to_bytes; 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. #[deriving(Clone, Eq)] pub struct Url { + /// The scheme part of a URL, such as `http`, `ftp` or `mailto`. scheme: ~str, + /// A URL subcomponent for user authentication. user: Option, + /// A domain name or IP address. For example, `www.example.com`. host: ~str, + /// A TCP port number, for example `8080`. port: Option<~str>, + /// The path component of a URL, for example `/users/jsmith`. path: ~str, + /// The query component of a URL. query: Query, + /// The fragment component. Does not include the leading hash or pound sign. fragment: Option<~str> } +/// An optional subcomponent of a URI authority component. #[deriving(Clone, Eq)] pub struct UserInfo { + /// The user name. user: ~str, + /// Password or other scheme-specific authentication information. pass: Option<~str> } +/// Represents the query component of a URI. pub type Query = ~[(~str, ~str)]; impl Url { From 2c1acd7998d9a99bd16ee59fe1fd68d1eece4c3e Mon Sep 17 00:00:00 2001 From: Dave Hodder Date: Sun, 1 Dec 2013 22:25:58 +0000 Subject: [PATCH 2/2] Add struct and type doc comments for extra::url::* Updated doc comments further, following suggestions from huonw in PR #10752. --- src/libextra/url.rs | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/src/libextra/url.rs b/src/libextra/url.rs index 034d7e110fbfe..4190bd9036b43 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, - /// 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> }