docs(headers): Update documentation of all remaining headers that use macros

2015-04-28 20:31:30 +02:00
parent 5a8cd31025
commit 14f46035b7
17 changed files with 98 additions and 85 deletions
--- a/src/header/common/allow.rs
+++ b/src/header/common/allow.rs
@@ -12,6 +12,11 @@ header! {
    #[doc="```plain"]
    #[doc="Allow = #method"]
    #[doc="```"]
+    #[doc=""]
+    #[doc="# Example values"]
+    #[doc="* `GET, HEAD, PUT`"]
+    #[doc="* `OPTIONS, GET, PUT, POST, DELETE, HEAD, TRACE, CONNECT, PATCH, fOObAr`"]
+    #[doc="* ``"]
    (Allow, "Allow") => (Method)*

    test_allow {
--- a/src/header/common/content_encoding.rs
+++ b/src/header/common/content_encoding.rs
@@ -16,9 +16,15 @@ header! {
    #[doc="```plain"]
    #[doc="Content-Encoding = 1#content-coding"]
    #[doc="```"]
+    #[doc=""]
+    #[doc="# Example values"]
+    #[doc="* `gzip`"]
    (ContentEncoding, "Content-Encoding") => (Encoding)+

-    test_content_encoding {}
+    test_content_encoding {
+        /// Testcase from the RFC
+        test_header!(test1, vec![b"gzip"], Some(ContentEncoding(vec![Encoding::Gzip])));
+    }
 }

 bench_header!(single, ContentEncoding, { vec![b"gzip".to_vec()] });
--- a/src/header/common/content_language.rs
+++ b/src/header/common/content_language.rs
@@ -13,6 +13,10 @@ header! {
    #[doc="```plain"]
    #[doc="Content-Language = 1#language-tag"]
    #[doc="```"]
+    #[doc=""]
+    #[doc="# Example values"]
+    #[doc="* `da`"]
+    #[doc="* `mi, en`"]
    (ContentLanguage, "Content-Language") => (QualityItem<Language>)+

    test_content_language {
--- a/src/header/common/content_length.rs
+++ b/src/header/common/content_length.rs
@@ -15,6 +15,9 @@ header! {
    #[doc="```plain"]
    #[doc="Content-Length = 1*DIGIT"]
    #[doc="```"]
+    #[doc=""]
+    #[doc="# Example values"]
+    #[doc="* `3495`"]
    (ContentLength, "Content-Length") => [u64]

    test_content_length {
--- a/src/header/common/content_type.rs
+++ b/src/header/common/content_type.rs
@@ -16,6 +16,9 @@ header! {
    #[doc="```plain"]
    #[doc="Content-Type = media-type"]
    #[doc="```"]
+    #[doc=""]
+    #[doc="# Example values"]
+    #[doc="* `text/html; charset=ISO-8859-4`"]
    (ContentType, "Content-Type") => [Mime]

    test_content_type {
--- a/src/header/common/date.rs
+++ b/src/header/common/date.rs
@@ -10,6 +10,9 @@ header! {
    #[doc="```plain"]
    #[doc="Date = HTTP-date"]
    #[doc="```"]
+    #[doc=""]
+    #[doc="# Example values"]
+    #[doc="* `Tue, 15 Nov 1994 08:12:31 GMT`"]
    (Date, "Date") => [HttpDate]

    test_date {
--- a/src/header/common/etag.rs
+++ b/src/header/common/etag.rs
@@ -17,63 +17,30 @@ header! {
    #[doc="```plain"]
    #[doc="ETag       = entity-tag"]
    #[doc="```"]
+    #[doc=""]
+    #[doc="# Example values"]
+    #[doc="* `\"xyzzy\"`"]
+    #[doc="* `W/\"xyzzy\"`"]
+    #[doc="* `\"\"`"]
    (ETag, "ETag") => [EntityTag]

    test_etag {
-        test_header!(test1, vec![b"\"xyzzy\""], Some(HeaderField(EntityTag::new(false, "xyzzy".to_string()))));
-        test_header!(test2, vec![b"W/\"xyzzy\""], Some(HeaderField(EntityTag::new(true, "xyzzy".to_string()))));
-        test_header!(test3, vec![b"\"\""], Some(HeaderField(EntityTag::new(false, "".to_string()))));
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::ETag;
-    use header::{Header,EntityTag};
-
-    #[test]
-    fn test_etag_successes() {
-        // Expected successes
-        let mut etag: Option<ETag>;
-
-        etag = Header::parse_header([b"\"foobar\"".to_vec()].as_ref());
-        assert_eq!(etag, Some(ETag(EntityTag::new(false, "foobar".to_string()))));
-
-        etag = Header::parse_header([b"\"\"".to_vec()].as_ref());
-        assert_eq!(etag, Some(ETag(EntityTag::new(false, "".to_string()))));
-
-        etag = Header::parse_header([b"W/\"weak-etag\"".to_vec()].as_ref());
-        assert_eq!(etag, Some(ETag(EntityTag::new(true, "weak-etag".to_string()))));
-
-        etag = Header::parse_header([b"W/\"\x65\x62\"".to_vec()].as_ref());
-        assert_eq!(etag, Some(ETag(EntityTag::new(true, "\u{0065}\u{0062}".to_string()))));
-
-        etag = Header::parse_header([b"W/\"\"".to_vec()].as_ref());
-        assert_eq!(etag, Some(ETag(EntityTag::new(true, "".to_string()))));
-    }
-
-    #[test]
-    fn test_etag_failures() {
-        // Expected failures
-        let mut etag: Option<ETag>;
-
-        etag = Header::parse_header([b"no-dquotes".to_vec()].as_ref());
-        assert_eq!(etag, None);
-
-        etag = Header::parse_header([b"w/\"the-first-w-is-case-sensitive\"".to_vec()].as_ref());
-        assert_eq!(etag, None);
-
-        etag = Header::parse_header([b"".to_vec()].as_ref());
-        assert_eq!(etag, None);
-
-        etag = Header::parse_header([b"\"unmatched-dquotes1".to_vec()].as_ref());
-        assert_eq!(etag, None);
-
-        etag = Header::parse_header([b"unmatched-dquotes2\"".to_vec()].as_ref());
-        assert_eq!(etag, None);
-
-        etag = Header::parse_header([b"matched-\"dquotes\"".to_vec()].as_ref());
-        assert_eq!(etag, None);
+        // From the RFC
+        test_header!(test1, vec![b"\"xyzzy\""], Some(ETag(EntityTag::new(false, "xyzzy".to_string()))));
+        test_header!(test2, vec![b"W/\"xyzzy\""], Some(ETag(EntityTag::new(true, "xyzzy".to_string()))));
+        test_header!(test3, vec![b"\"\""], Some(ETag(EntityTag::new(false, "".to_string()))));
+        // Own tests
+        test_header!(test4, vec![b"\"foobar\""], Some(ETag(EntityTag::new(false, "foobar".to_string()))));
+        test_header!(test5, vec![b"\"\""], Some(ETag(EntityTag::new(false, "".to_string()))));
+        test_header!(test6, vec![b"W/\"weak-etag\""], Some(ETag(EntityTag::new(true, "weak-etag".to_string()))));
+        test_header!(test7, vec![b"W/\"\x65\x62\""], Some(ETag(EntityTag::new(true, "\u{0065}\u{0062}".to_string()))));
+        test_header!(test8, vec![b"W/\"\""], Some(ETag(EntityTag::new(true, "".to_string()))));
+        test_header!(test9, vec![b"no-dquotes"], None::<ETag>);
+        test_header!(test10, vec![b"w/\"the-first-w-is-case-sensitive\""], None::<ETag>);
+        test_header!(test11, vec![b""], None::<ETag>);
+        test_header!(test12, vec![b"\"unmatched-dquotes1"], None::<ETag>);
+        test_header!(test13, vec![b"unmatched-dquotes2\""], None::<ETag>);
+        test_header!(test14, vec![b"matched-\"dquotes\""], None::<ETag>);
    }
 }

--- a/src/header/common/expires.rs
+++ b/src/header/common/expires.rs
@@ -14,6 +14,9 @@ header! {
    #[doc="```plain"]
    #[doc="Expires = HTTP-date"]
    #[doc="```"]
+    #[doc=""]
+    #[doc="# Example values"]
+    #[doc="* `Thu, 01 Dec 1994 16:00:00 GMT`"]
    (Expires, "Expires") => [HttpDate]

    test_expires {
--- a/src/header/common/last_modified.rs
+++ b/src/header/common/last_modified.rs
@@ -12,6 +12,9 @@ header! {
    #[doc="```plain"]
    #[doc="Expires = HTTP-date"]
    #[doc="```"]
+    #[doc=""]
+    #[doc="# Example values"]
+    #[doc="* `Sat, 29 Oct 1994 19:43:31 GMT`"]
    (LastModified, "Last-Modified") => [HttpDate]

    test_last_modified {
--- a/src/header/common/location.rs
+++ b/src/header/common/location.rs
@@ -11,6 +11,10 @@ header! {
    #[doc="```plain"]
    #[doc="Location = URI-reference"]
    #[doc="```"]
+    #[doc=""]
+    #[doc="# Example values"]
+    #[doc="* `/People.html#tim`"]
+    #[doc="* `http://www.example.net/index.html`"]
    // TODO: Use URL
    (Location, "Location") => [String]

--- a/src/header/common/mod.rs
+++ b/src/header/common/mod.rs
@@ -118,8 +118,10 @@ macro_rules! test_header {
            // Test parsing
            assert_eq!(val, $typed);
            // Test formatting
-            let res: &str = str::from_utf8($raw[0]).unwrap();
-            assert_eq!(format!("{}", $typed.unwrap()), res);
+            if $typed != None {
+                let res: &str = str::from_utf8($raw[0]).unwrap();
+                assert_eq!(format!("{}", $typed.unwrap()), res);
+            }
        }
    }
 }
--- a/src/header/common/referer.rs
+++ b/src/header/common/referer.rs
@@ -12,6 +12,9 @@ header! {
    #[doc="```plain"]
    #[doc="Referer = absolute-URI / partial-URI"]
    #[doc="```"]
+    #[doc=""]
+    #[doc="# Example values"]
+    #[doc="* `http://www.example.org/hypertext/Overview.html`"]
    // TODO: Use URL
    (Referer, "Referer") => [String]

--- a/src/header/common/server.rs
+++ b/src/header/common/server.rs
@@ -13,6 +13,9 @@ header! {
    #[doc="```plain"]
    #[doc="Server = product *( RWS ( product / comment ) )"]
    #[doc="```"]
+    #[doc=""]
+    #[doc="# Example values"]
+    #[doc="* `CERN/3.0 libwww/2.17`"]
    // TODO: Maybe parse as defined in the spec?
    (Server, "Server") => [String]

--- a/src/header/common/transfer_encoding.rs
+++ b/src/header/common/transfer_encoding.rs
@@ -13,6 +13,9 @@ header! {
    #[doc="```plain"]
    #[doc="Transfer-Encoding = 1#transfer-coding"]
    #[doc="```"]
+    #[doc=""]
+    #[doc="# Example values"]
+    #[doc="* `gzip, chunked`"]
    (TransferEncoding, "Transfer-Encoding") => (Encoding)+

    transfer_encoding {
--- a/src/header/common/upgrade.rs
+++ b/src/header/common/upgrade.rs
@@ -25,6 +25,9 @@ header! {
    #[doc="protocol-name    = token"]
    #[doc="protocol-version = token"]
    #[doc="```"]
+    #[doc=""]
+    #[doc="# Example values"]
+    #[doc="* `HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11`"]
    (Upgrade, "Upgrade") => (Protocol)+

    test_upgrade {
@@ -41,6 +44,7 @@ header! {
 }

 /// Protocol values that can appear in the Upgrade header.
+// TODO: Parse version part seperately
 #[derive(Clone, PartialEq, Debug)]
 pub enum Protocol {
    /// The websocket protocol.
--- a/src/header/common/user_agent.rs
+++ b/src/header/common/user_agent.rs
@@ -16,19 +16,19 @@ header! {
    #[doc="product         = token [\"/\" product-version]"]
    #[doc="product-version = token"]
    #[doc="```"]
-    // TODO: Maybe write parsing according to the spec? (Split the String)
+    #[doc=""]
+    #[doc="# Example values"]
+    #[doc="* `CERN-LineMode/2.15 libwww/2.17b3`"]
+    #[doc="* `Bunnies`"]
+    #[doc=""]
+    #[doc="# Notes"]
+    #[doc="* The parser does not split the value"]
    (UserAgent, "User-Agent") => [String]

    test_user_agent {
        // Testcase from RFC
        test_header!(test1, vec![b"CERN-LineMode/2.15 libwww/2.17b3"]);
+        // Own testcase
+        test_header!(test2, vec![b"Bunnies"], Some(UserAgent("Bunnies".to_string())));
    }
 }
-
-#[test] fn test_format() {
-    use std::borrow::ToOwned;
-    use header::Headers;
-    let mut head = Headers::new();
-    head.set(UserAgent("Bunnies".to_owned()));
-    assert!(head.to_string() == "User-Agent: Bunnies\r\n".to_owned());
-}
--- a/src/header/common/vary.rs
+++ b/src/header/common/vary.rs
@@ -14,28 +14,25 @@ header! {
    #[doc="```plain"]
    #[doc="Vary = \"*\" / 1#field-name"]
    #[doc="```"]
+    #[doc=""]
+    #[doc="# Example values"]
+    #[doc="* `accept-encoding, accept-language`"]
    (Vary, "Vary") => {Any / (UniCase<String>)+}

    test_vary {
        test_header!(test1, vec![b"accept-encoding, accept-language"]);
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::Vary;
-    use header::Header;
-
-    #[test]
-    fn test_vary() {
-        let mut vary: Option<Vary>;
-
-        vary = Header::parse_header([b"*".to_vec()].as_ref());
-        assert_eq!(vary, Some(Vary::Any));
-
-        vary = Header::parse_header([b"etag,cookie,allow".to_vec()].as_ref());
-        assert_eq!(vary, Some(Vary::Items(vec!["eTag".parse().unwrap(),
-                                                "cookIE".parse().unwrap(),
-                                                "AlLOw".parse().unwrap(),])));
+
+        #[test]
+        fn test2() {
+            let mut vary: Option<Vary>;
+
+            vary = Header::parse_header([b"*".to_vec()].as_ref());
+            assert_eq!(vary, Some(Vary::Any));
+
+            vary = Header::parse_header([b"etag,cookie,allow".to_vec()].as_ref());
+            assert_eq!(vary, Some(Vary::Items(vec!["eTag".parse().unwrap(),
+                                                    "cookIE".parse().unwrap(),
+                                                    "AlLOw".parse().unwrap(),])));
+        }
    }
 }