Merge pull request #567 from clatour/header-docs

docs(headers): add examples
hyperium · Jun 15, 2015 · febf303 · febf303
2 parents c37d857 + c940e84
commit febf303
Show file tree

Hide file tree

Showing 41 changed files with 856 additions and 0 deletions.
diff --git a/src/header/common/accept.rs b/src/header/common/accept.rs
@@ -27,6 +27,51 @@ header! {
     #[doc="* `audio/*; q=0.2, audio/basic` (`*` value won't parse correctly)"]
     #[doc="* `text/plain; q=0.5, text/html, text/x-dvi; q=0.8, text/x-c`"]
     #[doc=""]
+    #[doc="# Examples"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, Accept, qitem};"]
+    #[doc="use hyper::mime::{Mime, TopLevel, SubLevel};"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc=""]
+    #[doc="headers.set("]
+    #[doc="    Accept(vec!["]
+    #[doc="        qitem(Mime(TopLevel::Text, SubLevel::Html, vec![])),"]
+    #[doc="    ])"]
+    #[doc=");"]
+    #[doc="```"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, Accept, qitem};"]
+    #[doc="use hyper::mime::{Mime, TopLevel, SubLevel, Attr, Value};"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set("]
+    #[doc="    Accept(vec!["]
+    #[doc="        qitem(Mime(TopLevel::Application, SubLevel::Json,"]
+    #[doc="                   vec![(Attr::Charset, Value::Utf8)])),"]
+    #[doc="    ])"]
+    #[doc=");"]
+    #[doc="```"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, Accept, QualityItem, Quality, qitem};"]
+    #[doc="use hyper::mime::{Mime, TopLevel, SubLevel};"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc=""]
+    #[doc="headers.set("]
+    #[doc="    Accept(vec!["]
+    #[doc="        qitem(Mime(TopLevel::Text, SubLevel::Html, vec![])),"]
+    #[doc="        qitem(Mime(TopLevel::Application, SubLevel::Ext(\"xhtml+xml\".to_owned()), vec![])),"]
+    #[doc="        QualityItem::new(Mime(TopLevel::Application, SubLevel::Xml, vec![]),"]
+    #[doc="                         Quality(900)),"]
+    #[doc="                         qitem(Mime(TopLevel::Image, SubLevel::Ext(\"webp\".to_owned()), vec![])),
+"]
+    #[doc="                         QualityItem::new(Mime(TopLevel::Star, SubLevel::Star, vec![]),"]
+    #[doc="                                          Quality(800))"]
+    #[doc="    ])"]
+    #[doc=");"]
+    #[doc="```"]
+    #[doc=""]
     #[doc="# Notes"]
     #[doc="* Using always Mime types to represent `media-range` differs from the ABNF."]
     #[doc="* **FIXME**: `accept-ext` is not supported."]

diff --git a/src/header/common/accept_charset.rs b/src/header/common/accept_charset.rs
@@ -18,6 +18,35 @@ header! {
     #[doc=""]
     #[doc="# Example values"]
     #[doc="* `iso-8859-5, unicode-1-1;q=0.8`"]
+    #[doc=""]
+    #[doc="# Examples"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, AcceptCharset, Charset, qitem};"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set("]
+    #[doc="    AcceptCharset(vec![qitem(Charset::Us_Ascii)])"]
+    #[doc=");"]
+    #[doc="```"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, AcceptCharset, Charset, Quality, QualityItem};"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set("]
+    #[doc="    AcceptCharset(vec!["]
+    #[doc="        QualityItem::new(Charset::Us_Ascii, Quality(900)),"]
+    #[doc="        QualityItem::new(Charset::Iso_8859_10, Quality(200)),"]
+    #[doc="    ])"]
+    #[doc=");"]
+    #[doc="```"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, AcceptCharset, Charset, qitem};"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set("]
+    #[doc="    AcceptCharset(vec![qitem(Charset::Ext(\"utf-8\".to_owned()))])"]
+    #[doc=");"]
+    #[doc="```"]
     (AcceptCharset, "Accept-Charset") => (QualityItem<Charset>)+
 
     test_accept_charset {

diff --git a/src/header/common/accept_encoding.rs b/src/header/common/accept_encoding.rs
@@ -22,6 +22,40 @@ header! {
     #[doc="* `*`"]
     #[doc="* `compress;q=0.5, gzip;q=1`"]
     #[doc="* `gzip;q=1.0, identity; q=0.5, *;q=0`"]
+    #[doc=""]
+    #[doc="# Examples"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, AcceptEncoding, Encoding, qitem};"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set("]
+    #[doc="    AcceptEncoding(vec![qitem(Encoding::Chunked)])"]
+    #[doc=");"]
+    #[doc="```"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, AcceptEncoding, Encoding, qitem};"]
+    #[doc=" "]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set("]
+    #[doc="    AcceptEncoding(vec!["]
+    #[doc="        qitem(Encoding::Chunked),"]
+    #[doc="        qitem(Encoding::Gzip),"]
+    #[doc="        qitem(Encoding::Deflate),"]
+    #[doc="    ])"]
+    #[doc=");"]
+    #[doc="```"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, AcceptEncoding, Encoding, QualityItem, Quality, qitem};"]
+    #[doc=" "]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set("]
+    #[doc="    AcceptEncoding(vec!["]
+    #[doc="        qitem(Encoding::Chunked),"]
+    #[doc="        QualityItem::new(Encoding::Gzip, Quality(600)),"]
+    #[doc="        QualityItem::new(Encoding::EncodingExt(\"*\".to_owned()), Quality(0)),"]
+    #[doc="    ])"]
+    #[doc=");"]
+    #[doc="```"]
     (AcceptEncoding, "Accept-Encoding") => (QualityItem<Encoding>)*
 
     test_accept_encoding {

diff --git a/src/header/common/accept_language.rs b/src/header/common/accept_language.rs
@@ -17,6 +17,52 @@ header! {
     #[doc="# Example values"]
     #[doc="* `da, en-gb;q=0.8, en;q=0.7`"]
     #[doc="* `en-us;q=1.0, en;q=0.5, fr`"]
+    #[doc=""]
+    #[doc="# Examples"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, AcceptLanguage, Language, qitem};"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set("]
+    #[doc="    AcceptLanguage(vec!["]
+    #[doc="        qitem("]
+    #[doc="            Language {"]
+    #[doc="                 primary: \"en\".to_owned(),"]
+    #[doc="                 sub: Some(\"us\".to_owned()),"]
+    #[doc="            }"]
+    #[doc="        ),"]
+    #[doc="    ])"]
+    #[doc=");"]
+    #[doc="```"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, AcceptLanguage, Language, QualityItem, Quality, qitem};"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set("]
+    #[doc="    AcceptLanguage(vec!["]
+    #[doc="        qitem("]
+    #[doc="            Language {"]
+    #[doc="                primary: \"da\".to_owned(),"]
+    #[doc="                sub: None,"]
+    #[doc="             }"]
+    #[doc="        ),"]
+    #[doc="        QualityItem::new("]
+    #[doc="            Language {"]
+    #[doc="                primary: \"en\".to_owned(),"]
+    #[doc="                sub: Some(\"gb\".to_owned()),"]
+    #[doc="            },"]
+    #[doc="            Quality(800),"]
+    #[doc="        ),"]
+    #[doc="        QualityItem::new("]
+    #[doc="            Language {"]
+    #[doc="                primary: \"en\".to_owned(),"]
+    #[doc="                sub: None,"]
+    #[doc="            },"]
+    #[doc="            Quality(700),"]
+    #[doc="        ),"]
+    #[doc="    ])"]
+    #[doc=");"]
+    #[doc="```"]
     (AcceptLanguage, "Accept-Language") => (QualityItem<Language>)+
 
     test_accept_language {

diff --git a/src/header/common/accept_ranges.rs b/src/header/common/accept_ranges.rs
@@ -18,6 +18,33 @@ header! {
     #[doc="* `none`"]
     #[doc="* `unknown-unit`"]
     #[doc="```"]
+    #[doc=""]
+    #[doc="# Examples"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, AcceptRanges, RangeUnit};"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set(AcceptRanges(vec![RangeUnit::Bytes]));"]
+    #[doc="```"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, AcceptRanges, RangeUnit};"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set(AcceptRanges(vec![RangeUnit::None]));"]
+    #[doc="```"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, AcceptRanges, RangeUnit};"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set("]
+    #[doc="    AcceptRanges(vec!["]
+    #[doc="        RangeUnit::Unregistered(\"nibbles\".to_owned()),"]
+    #[doc="        RangeUnit::Bytes,"]
+    #[doc="        RangeUnit::Unregistered(\"doublets\".to_owned()),"]
+    #[doc="        RangeUnit::Unregistered(\"quadlets\".to_owned()),"]
+    #[doc="    ])"]
+    #[doc=");"]
+    #[doc="```"]
     (AcceptRanges, "Accept-Ranges") => (RangeUnit)+
 
     test_acccept_ranges {

diff --git a/src/header/common/access_control_allow_headers.rs b/src/header/common/access_control_allow_headers.rs
@@ -15,6 +15,41 @@ header! {
     #[doc=""]
     #[doc="# Example values"]
     #[doc="* `accept-language, date`"]
+    #[doc=""]
+    #[doc="# Examples"]
+    #[doc="```"]
+    #[doc="# extern crate hyper;"]
+    #[doc="# extern crate unicase;"]
+    #[doc="# fn main() {"]
+    #[doc="// extern crate unicase;"]
+    #[doc=""]
+    #[doc="use hyper::header::{Headers, AccessControlAllowHeaders};"]
+    #[doc="use unicase::UniCase;"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set("]
+    #[doc="    AccessControlAllowHeaders(vec![UniCase(\"date\".to_owned())])"]
+    #[doc=");"]
+    #[doc="# }"]
+    #[doc="```"]
+    #[doc="```"]
+    #[doc="# extern crate hyper;"]
+    #[doc="# extern crate unicase;"]
+    #[doc="# fn main() {"]
+    #[doc="// extern crate unicase;"]
+    #[doc=""]
+    #[doc="use hyper::header::{Headers, AccessControlAllowHeaders};"]
+    #[doc="use unicase::UniCase;"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set("]
+    #[doc="    AccessControlAllowHeaders(vec!["]
+    #[doc="        UniCase(\"accept-language\".to_owned()),"]
+    #[doc="        UniCase(\"date\".to_owned()),"]
+    #[doc="    ])"]
+    #[doc=");"]
+    #[doc="# }"]
+    #[doc="```"]
     (AccessControlAllowHeaders, "Access-Control-Allow-Headers") => (UniCase<String>)*
 
     test_access_control_allow_headers {

diff --git a/src/header/common/access_control_allow_methods.rs b/src/header/common/access_control_allow_methods.rs
@@ -15,6 +15,31 @@ header! {
     #[doc=""]
     #[doc="# Example values"]
     #[doc="* `PUT, DELETE, XMODIFY`"]
+    #[doc=""]
+    #[doc="# Examples"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, AccessControlAllowMethods};"]
+    #[doc="use hyper::method::Method;"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set("]
+    #[doc="    AccessControlAllowMethods(vec![Method::Get])"]
+    #[doc=");"]
+    #[doc="```"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, AccessControlAllowMethods};"]
+    #[doc="use hyper::method::Method;"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set("]
+    #[doc="    AccessControlAllowMethods(vec!["]
+    #[doc="        Method::Get,"]
+    #[doc="        Method::Post,"]
+    #[doc="        Method::Patch,"]
+    #[doc="        Method::Extension(\"COPY\".to_owned()),"]
+    #[doc="    ])"]
+    #[doc=");"]
+    #[doc="```"]
     (AccessControlAllowMethods, "Access-Control-Allow-Methods") => (Method)*
 
     test_access_control_allow_methods {

diff --git a/src/header/common/access_control_allow_origin.rs b/src/header/common/access_control_allow_origin.rs
@@ -20,6 +20,33 @@ use header::{Header, HeaderFormat};
 /// * `null`
 /// * `*`
 /// * `http://google.com/`
+/// 
+/// # Examples
+/// ```
+/// use hyper::header::{Headers, AccessControlAllowOrigin};
+///
+/// let mut headers = Headers::new();
+/// headers.set(
+///     AccessControlAllowOrigin::Any
+/// );
+/// ```
+/// ```
+/// use hyper::header::{Headers, AccessControlAllowOrigin};
+///
+/// let mut headers = Headers::new();
+/// headers.set(
+///     AccessControlAllowOrigin::Null,
+/// );
+/// ```
+/// ```
+/// use hyper::header::{Headers, AccessControlAllowOrigin};
+/// use hyper::Url;
+///
+/// let mut headers = Headers::new();
+/// headers.set(
+///     AccessControlAllowOrigin::Value(Url::parse("http://hyper.rs").unwrap())
+/// );
+/// ```
 #[derive(Clone, PartialEq, Debug)]
 pub enum AccessControlAllowOrigin {
     /// Allow all origins

diff --git a/src/header/common/access_control_max_age.rs b/src/header/common/access_control_max_age.rs
@@ -12,6 +12,14 @@ header! {
     #[doc=""]
     #[doc="# Example values"]
     #[doc="* `531`"]
+    #[doc=""]
+    #[doc="# Examples"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, AccessControlMaxAge};"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set(AccessControlMaxAge(1728000u32));"]
+    #[doc="```"]
     (AccessControlMaxAge, "Access-Control-Max-Age") => [u32]
 
     test_access_control_max_age {

diff --git a/src/header/common/access_control_request_headers.rs b/src/header/common/access_control_request_headers.rs
@@ -15,6 +15,41 @@ header! {
     #[doc=""]
     #[doc="# Example values"]
     #[doc="* `accept-language, date`"]
+    #[doc=""]
+    #[doc="# Examples"]
+    #[doc="```"]
+    #[doc="# extern crate hyper;"]
+    #[doc="# extern crate unicase;"]
+    #[doc="# fn main() {"]
+    #[doc="// extern crate unicase;"]
+    #[doc=""]
+    #[doc="use hyper::header::{Headers, AccessControlRequestHeaders};"]
+    #[doc="use unicase::UniCase;"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set("]
+    #[doc="    AccessControlRequestHeaders(vec![UniCase(\"date\".to_owned())])"]
+    #[doc=");"]
+    #[doc="# }"]
+    #[doc="```"]
+    #[doc="```"]
+    #[doc="# extern crate hyper;"]
+    #[doc="# extern crate unicase;"]
+    #[doc="# fn main() {"]
+    #[doc="// extern crate unicase;"]
+    #[doc=""]
+    #[doc="use hyper::header::{Headers, AccessControlRequestHeaders};"]
+    #[doc="use unicase::UniCase;"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set("]
+    #[doc="    AccessControlRequestHeaders(vec!["]
+    #[doc="        UniCase(\"accept-language\".to_owned()),"]
+    #[doc="        UniCase(\"date\".to_owned()),"]
+    #[doc="    ])"]
+    #[doc=");"]
+    #[doc="# }"]
+    #[doc="```"]
     (AccessControlRequestHeaders, "Access-Control-Request-Headers") => (UniCase<String>)*
 
     test_access_control_request_headers {

diff --git a/src/header/common/access_control_request_method.rs b/src/header/common/access_control_request_method.rs
@@ -13,6 +13,15 @@ header! {
     #[doc=""]
     #[doc="# Example values"]
     #[doc="* `GET`"]
+    #[doc=""]
+    #[doc="# Examples"]
+    #[doc="```"]
+    #[doc="use hyper::header::{Headers, AccessControlRequestMethod};"]
+    #[doc="use hyper::method::Method;"]
+    #[doc=""]
+    #[doc="let mut headers = Headers::new();"]
+    #[doc="headers.set(AccessControlRequestMethod(Method::Get));"]
+    #[doc="```"]
     (AccessControlRequestMethod, "Access-Control-Request-Method") => [Method]
 
     test_access_control_request_method {