From bca1dd4f9e65b3ea14a2fdf3d3cc0021c17124a3 Mon Sep 17 00:00:00 2001 From: Nikolay Kim Date: Wed, 20 Dec 2017 23:19:21 -0800 Subject: [PATCH] update doc strings --- examples/multipart/src/main.rs | 47 +++++++++++++------------- guide/src/qs_7.md | 4 --- src/error.rs | 1 + src/handler.rs | 1 + src/httprequest.rs | 33 +++++++++++++++++- src/httpresponse.rs | 62 +++++++++++++++++++++++++++------- 6 files changed, 107 insertions(+), 41 deletions(-) diff --git a/examples/multipart/src/main.rs b/examples/multipart/src/main.rs index 0778c051c..41204bef0 100644 --- a/examples/multipart/src/main.rs +++ b/examples/multipart/src/main.rs @@ -14,32 +14,31 @@ fn index(mut req: HttpRequest) -> Box> { println!("{:?}", req); - Box::new( - req.multipart() // <- get multipart stream for current request - .from_err() // <- convert multipart errors - .and_then(|item| { // <- iterate over multipart items - match item { - // Handle multipart Field - multipart::MultipartItem::Field(field) => { - println!("==== FIELD ==== {:?}", field); + req.multipart() // <- get multipart stream for current request + .from_err() // <- convert multipart errors + .and_then(|item| { // <- iterate over multipart items + match item { + // Handle multipart Field + multipart::MultipartItem::Field(field) => { + println!("==== FIELD ==== {:?}", field); - // Field in turn is stream of *Bytes* object - Either::A( - field.map_err(Error::from) - .map(|chunk| { - println!("-- CHUNK: \n{}", - std::str::from_utf8(&chunk).unwrap());}) - .finish()) - }, - multipart::MultipartItem::Nested(mp) => { - // Or item could be nested Multipart stream - Either::B(result(Ok(()))) - } + // Field in turn is stream of *Bytes* object + Either::A( + field.map_err(Error::from) + .map(|chunk| { + println!("-- CHUNK: \n{}", + std::str::from_utf8(&chunk).unwrap());}) + .finish()) + }, + multipart::MultipartItem::Nested(mp) => { + // Or item could be nested Multipart stream + Either::B(result(Ok(()))) } - }) - .finish() // <- Stream::finish() combinator from actix - .map(|_| httpcodes::HTTPOk.response()) - ) + } + }) + .finish() // <- Stream::finish() combinator from actix + .map(|_| httpcodes::HTTPOk.response()) + .responder() } fn main() { diff --git a/guide/src/qs_7.md b/guide/src/qs_7.md index 7e341c889..8385bdbd4 100644 --- a/guide/src/qs_7.md +++ b/guide/src/qs_7.md @@ -168,10 +168,6 @@ fn index(req: HttpRequest) -> HttpResponse { # fn main() {} ``` -## Cookies - -[WIP] - ## Multipart body Actix provides multipart stream support. diff --git a/src/error.rs b/src/error.rs index ea9f06526..ef4b65c56 100644 --- a/src/error.rs +++ b/src/error.rs @@ -115,6 +115,7 @@ impl ResponseError for header::InvalidHeaderValue {} impl ResponseError for Canceled {} /// Internal error +#[doc(hidden)] #[derive(Fail, Debug)] #[fail(display="Unexpected task frame")] pub struct UnexpectedTaskFrame; diff --git a/src/handler.rs b/src/handler.rs index 6ad426d53..f58513a95 100644 --- a/src/handler.rs +++ b/src/handler.rs @@ -36,6 +36,7 @@ pub trait Responder { fn respond_to(self, req: HttpRequest) -> Result; } +#[doc(hidden)] /// Convinience trait that convert `Future` object into `Boxed` future pub trait AsyncResponder: Sized { fn responder(self) -> Box>; diff --git a/src/httprequest.rs b/src/httprequest.rs index dd28282be..1f2e9eb05 100644 --- a/src/httprequest.rs +++ b/src/httprequest.rs @@ -432,9 +432,40 @@ impl HttpRequest { msg.payload.as_mut().unwrap() } - /// Return stream to process BODY as multipart. + /// Return stream to http payload processes as multipart. /// /// Content-type: multipart/form-data; + /// + /// ```rust + /// # extern crate actix; + /// # extern crate actix_web; + /// # extern crate env_logger; + /// # extern crate futures; + /// # use std::str; + /// # use actix::*; + /// # use actix_web::*; + /// # use futures::{Future, Stream}; + /// # use futures::future::{ok, result, Either}; + /// fn index(mut req: HttpRequest) -> Box> { + /// req.multipart().from_err() // <- get multipart stream for current request + /// .and_then(|item| match item { // <- iterate over multipart items + /// multipart::MultipartItem::Field(field) => { + /// // Field in turn is stream of *Bytes* object + /// Either::A(field.from_err() + /// .map(|c| println!("-- CHUNK: \n{:?}", str::from_utf8(&c))) + /// .finish()) + /// }, + /// multipart::MultipartItem::Nested(mp) => { + /// // Or item could be nested Multipart stream + /// Either::B(ok(())) + /// } + /// }) + /// .finish() // <- Stream::finish() combinator from actix + /// .map(|_| httpcodes::HTTPOk.response()) + /// .responder() + /// } + /// # fn main() {} + /// ``` pub fn multipart(&mut self) -> Multipart { Multipart::from_request(self) } diff --git a/src/httpresponse.rs b/src/httpresponse.rs index f8b410877..4b7b25a29 100644 --- a/src/httpresponse.rs +++ b/src/httpresponse.rs @@ -227,7 +227,9 @@ pub struct HttpResponseBuilder { } impl HttpResponseBuilder { - /// Set the HTTP version of this response. + /// Set HTTP version of this response. + /// + /// By default response's http version depends on request's version. #[inline] pub fn version(&mut self, version: Version) -> &mut Self { if let Some(parts) = parts(&mut self.response, &self.err) { @@ -236,16 +238,24 @@ impl HttpResponseBuilder { self } - /// Set the `StatusCode` for this response. - #[inline] - pub fn status(&mut self, status: StatusCode) -> &mut Self { - if let Some(parts) = parts(&mut self.response, &self.err) { - parts.status = status; - } - self - } - /// Set a header. + /// + /// ```rust + /// # extern crate http; + /// # extern crate actix_web; + /// # use actix_web::*; + /// # use actix_web::httpcodes::*; + /// # + /// use http::header; + /// + /// fn index(req: HttpRequest) -> Result { + /// Ok(HTTPOk.build() + /// .header("X-TEST", "value") + /// .header(header::CONTENT_TYPE, "application/json") + /// .finish()?) + /// } + /// fn main() {} + /// ``` #[inline] pub fn header(&mut self, key: K, value: V) -> &mut Self where HeaderName: HttpTryFrom, @@ -289,6 +299,7 @@ impl HttpResponseBuilder { /// Set connection type #[inline] + #[doc(hidden)] pub fn connection_type(&mut self, conn: ConnectionType) -> &mut Self { if let Some(parts) = parts(&mut self.response, &self.err) { parts.connection_type = Some(conn); @@ -298,6 +309,7 @@ impl HttpResponseBuilder { /// Set connection type to Upgrade #[inline] + #[doc(hidden)] pub fn upgrade(&mut self) -> &mut Self { self.connection_type(ConnectionType::Upgrade) } @@ -332,6 +344,27 @@ impl HttpResponseBuilder { } /// Set a cookie + /// + /// ```rust + /// # extern crate actix_web; + /// # use actix_web::*; + /// # use actix_web::httpcodes::*; + /// # + /// use actix_web::headers::Cookie; + /// + /// fn index(req: HttpRequest) -> Result { + /// Ok(HTTPOk.build() + /// .cookie( + /// Cookie::build("name", "value") + /// .domain("www.rust-lang.org") + /// .path("/") + /// .secure(true) + /// .http_only(true) + /// .finish()) + /// .finish()?) + /// } + /// fn main() {} + /// ``` pub fn cookie<'c>(&mut self, cookie: Cookie<'c>) -> &mut Self { if self.cookies.is_none() { let mut jar = CookieJar::new(); @@ -343,7 +376,7 @@ impl HttpResponseBuilder { self } - /// Remote cookie, cookie has to be cookie from `HttpRequest::cookies()` method. + /// Remove cookie, cookie has to be cookie from `HttpRequest::cookies()` method. pub fn del_cookie<'a>(&mut self, cookie: &Cookie<'a>) -> &mut Self { { if self.cookies.is_none() { @@ -357,7 +390,7 @@ impl HttpResponseBuilder { self } - /// Calls provided closure with builder reference if value is true. + /// This method calls provided closure with builder reference if value is true. pub fn if_true(&mut self, value: bool, f: F) -> &mut Self where F: Fn(&mut HttpResponseBuilder) + 'static { @@ -368,6 +401,7 @@ impl HttpResponseBuilder { } /// Set a body and generate `HttpResponse`. + /// /// `HttpResponseBuilder` can not be used after this call. pub fn body>(&mut self, body: B) -> Result { if let Some(e) = self.err.take() { @@ -386,6 +420,8 @@ impl HttpResponseBuilder { } /// Set a json body and generate `HttpResponse` + /// + /// `HttpResponseBuilder` can not be used after this call. pub fn json(&mut self, value: T) -> Result { let body = serde_json::to_string(&value)?; @@ -402,6 +438,8 @@ impl HttpResponseBuilder { } /// Set an empty body and generate `HttpResponse` + /// + /// `HttpResponseBuilder` can not be used after this call. pub fn finish(&mut self) -> Result { self.body(Body::Empty) }