Document the Punycode and application/x-www-form-urlencoded modules.

src/form_urlencoded.rs

@@ -6,10 +6,12 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-/// Parser and serializer for `application/x-www-form-urlencoded`
-///
-/// Converts between a string (such as an URL’s query string)
-/// and a list of name/value pairs.
+//! Parser and serializer for the [`application/x-www-form-urlencoded` format](
+//! http://url.spec.whatwg.org/#application/x-www-form-urlencoded),
+//! as used by HTML forms.
+//!
+//! Converts between a string (such as an URL’s query string)
+//! and a sequence of (name, value) pairs.
 
 use std::str;
 
@@ -22,11 +24,23 @@ use super::{percent_encode_to, percent_decode};
 use encode_sets::FORM_URLENCODED_ENCODE_SET;
 
 
+/// Convert a string in the `application/x-www-form-urlencoded` format
+/// into a vector of (name, value) pairs.
+#[inline]
 pub fn parse_str(input: &str) -> Vec<(String, String)> {
     parse_bytes(input.as_bytes(), None, false, false).unwrap()
 }
 
 
+/// Convert a byte string in the `application/x-www-form-urlencoded` format
+/// into a vector of (name, value) pairs.
+///
+/// Arguments:
+///
+/// * `encoding_override`: The character encoding each name and values is decoded as
+///    after percent-decoding. Defaults to UTF-8.
+/// * `use_charset`: The *use _charset_ flag*. If in doubt, set to `false`.
+/// * `isindex`: The *isindex flag*. If in doubt, set to `false`.
 pub fn parse_bytes(input: &[u8], encoding_override: Option<EncodingRef>,
                    mut use_charset: bool, mut isindex: bool) -> Option<Vec<(String, String)>> {
     let mut encoding_override = encoding_override.unwrap_or(UTF_8 as EncodingRef);
@@ -77,12 +91,19 @@ pub fn parse_bytes(input: &[u8], encoding_override: Option<EncodingRef>,
 }
 
 
+/// Convert an iterator of (name, value) pairs
+/// into a string in the `application/x-www-form-urlencoded` format.
+///
+/// Arguments:
+///
+/// * `encoding_override`: The character encoding each name and values is encoded as
+///    before percent-encoding. Defaults to UTF-8.
 pub fn serialize<'a, I: Iterator<(&'a str, &'a str)>>(
         mut pairs: I, encoding_override: Option<EncodingRef>)
         -> String {
     #[inline]
     fn byte_serialize(input: &str, output: &mut String,
-                     encoding_override: Option<EncodingRef>) {
+                      encoding_override: Option<EncodingRef>) {
         let keep_alive;
         let input = match encoding_override {
             None => input.as_bytes(),  // "Encode" to UTF-8

src/punycode.rs

@@ -6,7 +6,12 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-/// Punycode implementation: http://tools.ietf.org/html/rfc3492
+//! Punycode ([RFC 3492](http://tools.ietf.org/html/rfc3492)) implementation.
+//!
+//! Since Punycode fundamentally works on unicode code points,
+//! `encode` and `decode` take and return slices and vectors of `char`.
+//! `encode_str` and `decode_to_string` provide convenience wrappers
+//! that convert from and to Rust’s UTF-8 based `str` and `String` types.
 
 use std::u32;
 use std::char;
@@ -37,6 +42,7 @@ fn adapt(mut delta: u32, num_points: u32, first_time: bool) -> u32 {
 
 
 /// Convert Punycode to Unicode.
+///
 /// Return None on malformed input or overflow.
 /// Overflow can only happen on inputs that take more than
 /// 63 encoded bytes, the DNS limit on domain name labels.
@@ -111,12 +117,17 @@ pub fn decode(input: &str) -> Option<Vec<char>> {
 }
 
 
+/// Convert an Unicode `str` to Punycode.
+///
+/// This is a convenience wrapper around `encode`.
+#[inline]
 pub fn encode_str(input: &str) -> Option<String> {
     encode(input.chars().collect::<Vec<char>>().as_slice())
 }
 
 
 /// Convert Unicode to Punycode.
+///
 /// Return None on overflow, which can only happen on inputs that would take more than
 /// 63 encoded bytes, the DNS limit on domain name labels.
 pub fn encode(input: &[char]) -> Option<String> {