Add function doc comments for extra::url::*

Author: dhodder

src/libextra/url.rs

@@ -1,4 +1,4 @@
-// Copyright 2012-2013 The Rust Project Developers. See the COPYRIGHT
+// Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
 // file at the top-level directory of this distribution and at
 // http://rust-lang.org/COPYRIGHT.
 //
@@ -139,10 +139,19 @@ fn encode_inner(s: &str, full_url: bool) -> ~str {
 }
 
 /**
- * Encodes a URI by replacing reserved characters with percent encoded
+ * Encodes a URI by replacing reserved characters with percent-encoded
  * character sequences.
  *
  * This function is compliant with RFC 3986.
+ *
+ * # Example
+ *
+ * ```rust
+ * use extra::url::encode;
+ *
+ * let url = encode(&"https://example.com/Rust (programming language)");
+ * println!("{}", url); // https://example.com/Rust%20(programming%20language)
+ * ```
  */
 pub fn encode(s: &str) -> ~str {
     encode_inner(s, true)
@@ -206,9 +215,18 @@ fn decode_inner(s: &str, full_url: bool) -> ~str {
 }
 
 /**
- * Decode a string encoded with percent encoding.
+ * Decodes a percent-encoded string representing a URI.
  *
- * This will only decode escape sequences generated by encode.
+ * This will only decode escape sequences generated by `encode`.
+ *
+ * # Example
+ *
+ * ```rust
+ * use extra::url::decode;
+ *
+ * let url = decode(&"https://example.com/Rust%20(programming%20language)");
+ * println!("{}", url); // https://example.com/Rust (programming language)
+ * ```
  */
 pub fn decode(s: &str) -> ~str {
     decode_inner(s, true)
@@ -410,7 +428,23 @@ pub fn query_to_str(query: &Query) -> ~str {
     return strvec.connect("&");
 }
 
-// returns the scheme and the rest of the url, or a parsing error
+/**
+ * Returns a tuple of the URI scheme and the rest of the URI, or a parsing error.
+ *
+ * Does not include the separating `:` character.
+ *
+ * # Example
+ *
+ * ```rust
+ * use extra::url::get_scheme;
+ *
+ * let scheme = match get_scheme("https://example.com/") {
+ *     Ok((sch, _)) => sch,
+ *     Err(_) => ~"(None)",
+ * };
+ * println!("Scheme in use: {}.", scheme); // Scheme in use: https.
+ * ```
+ */
 pub fn get_scheme(rawurl: &str) -> Result<(~str, ~str), ~str> {
     for (i,c) in rawurl.chars().enumerate() {
         match c {
@@ -654,18 +688,16 @@ fn get_query_fragment(rawurl: &str) ->
 }
 
 /**
- * Parse a `str` to a `url`
+ * Parses a URL, converting it from a string to `Url` representation.
  *
  * # Arguments
  *
- * `rawurl` - a string representing a full url, including scheme.
+ * `rawurl` - a string representing the full URL, including scheme.
  *
  * # Returns
  *
- * a `url` that contains the parsed representation of the url.
- *
+ * A `Url` struct type representing the URL.
  */
-
 pub fn from_str(rawurl: &str) -> Result<Url, ~str> {
     // scheme
     let (scheme, rest) = match get_scheme(rawurl) {
@@ -705,19 +737,18 @@ impl FromStr for Url {
 }
 
 /**
- * Format a `url` as a string
+ * Converts a URL from `Url` to string representation.
  *
  * # Arguments
  *
- * `url` - a url.
+ * `url` - a URL.
  *
  * # Returns
  *
- * a `str` that contains the formatted url. Note that this will usually
- * be an inverse of `from_str` but might strip out unneeded separators.
+ * A string that contains the formatted URL. Note that this will usually
+ * be an inverse of `from_str` but might strip out unneeded separators;
  * for example, "http://somehost.com?", when parsed and formatted, will
  * result in just "http://somehost.com".
- *
  */
 pub fn to_str(url: &Url) -> ~str {
     let user = match url.user {