rwf2
/
Rocket
mirror of https://github.com/rwf2/Rocket.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Use inter/intra-crate links in all documentation.

This commit is contained in:
Sergio Benitez 2018-10-06 06:25:17 -07:00
parent 2839aca8ce
commit 28f2a33abd
51 changed files with 484 additions and 544 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
contrib/lib/src/databases.rs
View File

@ -26,9 +26,6 @@
//! support can be easily extended by implementing the [`Poolable`] trait. See
//! [Extending](#extending) for more.
//!
//! [`r2d2`]: https://crates.io/crates/r2d2
//! [request guards]: [rocket::FromRequest]
//!
//! ## Example
//!
//! Before using this library, the feature corresponding to your database type
@ -204,8 +201,6 @@
//! generates an implementation of the [`Deref`](::std::ops::Deref) trait with
//! the internal `Poolable` type as the target.
//!
//! [`FromRequest`]: /rocket/request/trait.FromRequest.html
//!
//! The macro will also generate two inherent methods on the decorated type:
//!
//! * `fn fairing() -> impl Fairing`
@ -316,14 +311,14 @@
//! The list below includes all presently supported database adapters and their
//! corresponding [`Poolable`] type.
//!
//! | Kind | Driver | [`Poolable`] Type | Feature |
//! | Kind | Driver | `Poolable` Type | Feature |
//! |----------|-----------------------|--------------------------------|------------------------|
//! | MySQL | [Diesel] | [`diesel::MysqlConnection`] | `diesel_mysql_pool` |
//! | MySQL | [`rust-mysql-simple`] | [`mysql::conn`] | `mysql_pool` |
//! | MySQL | [`rust-mysql-simple`] | [`mysql::Conn`] | `mysql_pool` |
//! | Postgres | [Diesel] | [`diesel::PgConnection`] | `diesel_postgres_pool` |
//! | Postgres | [Rust-Postgres] | [`postgres::Connection`] | `postgres_pool` |
//! | Sqlite | [Diesel] | [`diesel::SqliteConnection`] | `diesel_sqlite_pool` |
//! | Sqlite | [`Rustqlite`] | [`rusqlite::Connection`] | `sqlite_pool` |
//! | Sqlite | [Rustqlite] | [`rusqlite::Connection`] | `sqlite_pool` |
//! | Neo4j | [`rusted_cypher`] | [`rusted_cypher::GraphClient`] | `cypher_pool` |
//! | Redis | [`redis-rs`] | [`redis::Connection`] | `redis_pool` |
//!
@ -338,7 +333,7 @@
//! [`diesel::MysqlConnection`]: http://docs.diesel.rs/diesel/mysql/struct.MysqlConnection.html
//! [`redis-rs`]: https://github.com/mitsuhiko/redis-rs
//! [`rusted_cypher`]: https://github.com/livioribeiro/rusted-cypher
//! [`Rustqlite`]: https://github.com/jgallagher/rusqlite
//! [Rustqlite]: https://github.com/jgallagher/rusqlite
//! [Rust-Postgres]: https://github.com/sfackler/rust-postgres
//! [`rust-mysql-simple`]: https://github.com/blackbeam/rust-mysql-simple
//! [`diesel::PgConnection`]: http://docs.diesel.rs/diesel/pg/struct.PgConnection.html
@ -355,6 +350,10 @@
//! database-like struct that can be pooled by `r2d2`) is as easy as
//! implementing the [`Poolable`] trait. See the documentation for [`Poolable`]
//! for more details on how to implement it.
//!
//! [`FromRequest`]: rocket::FromRequest
//! [request guards]: rocket::FromRequest
//! [`Poolable`]: databases::Poolable
pub extern crate r2d2;
@ -455,7 +454,7 @@ pub enum DatabaseConfigError {
/// configuration.
MissingKey,
/// The configuration associated with the key isn't a
/// [Table](/rocket/config/type.Table.html).
/// [Table](::rocket::config::Table).
MalformedConfiguration,
/// The required `url` key is missing.
MissingUrl,
@ -612,9 +611,6 @@ impl<'a> Display for DatabaseConfigError {
/// `foo::ConnectionManager`
/// * `foo::Error`, errors resulting from manager instantiation
///
/// [`r2d2`]: https://crates.io/crates/r2d2
/// [`r2d2::ManageConnection`]: http://docs.rs/r2d2/0.8/r2d2/trait.ManageConnection.html
///
/// In order for Rocket to generate the required code to automatically provision
/// a r2d2 connection pool into application state, the `Poolable` trait needs to
/// be implemented for the connection type. The following example implements
@ -622,10 +618,9 @@ impl<'a> Display for DatabaseConfigError {
///
/// ```rust
/// use rocket_contrib::databases::{r2d2, DbError, DatabaseConfig, Poolable};
///
/// # mod foo {
/// # use rocket_contrib::databases::r2d2;
/// # use std::fmt;
/// # use rocket_contrib::databases::r2d2;
/// # #[derive(Debug)] pub struct Error;
/// # impl ::std::error::Error for Error { }
/// # impl fmt::Display for Error {
@ -637,6 +632,10 @@ impl<'a> Display for DatabaseConfigError {
/// #
/// # type Result<T> = ::std::result::Result<T, Error>;
/// #
/// # impl ConnectionManager {
/// # pub fn new(url: &str) -> Result<Self> { Err(Error) }
/// # }
/// #
/// # impl self::r2d2::ManageConnection for ConnectionManager {
/// # type Connection = Connection;
/// # type Error = Error;
@ -651,7 +650,6 @@ impl<'a> Display for DatabaseConfigError {
/// type Error = DbError<foo::Error>;
///
/// fn pool(config: DatabaseConfig) -> Result<r2d2::Pool<Self::Manager>, Self::Error> {
/// # let _ = config; /*
/// let manager = foo::ConnectionManager::new(config.url)
/// .map_err(DbError::Custom)?;
///
@ -659,8 +657,6 @@ impl<'a> Display for DatabaseConfigError {
/// .max_size(config.pool_size)
/// .build(manager)
/// .map_err(DbError::PoolError)
/// # */
/// # Err(DbError::Custom(foo::Error))
/// }
/// }
/// ```

32
contrib/lib/src/json.rs
View File

@ -164,8 +164,8 @@ impl<T> DerefMut for Json<T> {
/// this type implements [`Responder`], allowing a value of this type to be
/// returned directly from a handler.
///
/// [`Value`]: https://docs.rs/serde_json/1.0.2/serde_json/value/enum.Value.html
/// [`Responder`]: /rocket/response/trait.Responder.html
/// [`Value`]: serde_json::value
/// [`Responder`]: rocket::response::Responder
///
/// # `Responder`
///
@ -175,16 +175,18 @@ impl<T> DerefMut for Json<T> {
///
/// # Usage
///
/// A value of this type is constructed via the
/// [`json!`](/rocket_contrib/macro.json.html) macro. The macro and this type
/// are typically used to construct JSON values in an ad-hoc fashion during
/// request handling. This looks something like:
/// A value of this type is constructed via the [`json!`](json) macro. The macro
/// and this type are typically used to construct JSON values in an ad-hoc
/// fashion during request handling. This looks something like:
///
/// ```rust,ignore
/// ```rust
/// # #![feature(proc_macro_hygiene, decl_macro)]
/// # #[macro_use] extern crate rocket;
/// # #[macro_use] extern crate rocket_contrib;
/// use rocket_contrib::JsonValue;
///
/// #[get("/item")]
/// fn get_item() -> JsonValue {
/// #[get("/json")]
/// fn get_json() -> JsonValue {
/// json!({
/// "id": 83,
/// "values": [1, 2, 3, 4]
@ -259,15 +261,17 @@ impl<'a> Responder<'a> for JsonValue {
/// To import the macro, add the `#[macro_use]` attribute to the `extern crate
/// rocket_contrib` invocation:
///
/// ```rust,ignore
/// ```rust
/// #[macro_use] extern crate rocket_contrib;
/// ```
///
/// The return type of a `json!` invocation is
/// [`JsonValue`](/rocket_contrib/struct.JsonValue.html). A value created with
/// this macro can be returned from a handler as follows:
/// The return type of a `json!` invocation is [`JsonValue`]. A value created
/// with this macro can be returned from a handler as follows:
///
/// ```rust,ignore
/// ```rust
/// # #![feature(proc_macro_hygiene, decl_macro)]
/// # #[macro_use] extern crate rocket;
/// # #[macro_use] extern crate rocket_contrib;
/// use rocket_contrib::JsonValue;
///
/// #[get("/json")]

18
contrib/lib/src/lib.rs
View File

@ -10,28 +10,26 @@
//!
//! These libraries are always kept in-sync with the core Rocket library. They
//! provide common, but not fundamental, abstractions to be used by Rocket
//! applications. In particular, contributor libraries typically export types
//! implementing a combination of the `FromRequest`, `FromParam`, and
//! `Responder` traits.
//! applications.
//!
//! Each module in this library is held behind a feature flag, with the most
//! common modules exposed by default. The present feature list is below, with
//! an asterisk next to the features that are enabled by default:
//!
//! * [json*](struct.Json.html)
//! * [json*](Json)
//! * [static_files*](static_files)
//! * [msgpack](struct.MsgPack.html)
//! * [handlebars_templates](struct.Template.html)
//! * [tera_templates](struct.Template.html)
//! * [uuid](struct.Uuid.html)
//! * [${database}_pool](databases/index.html)
//! * [msgpack](MsgPack)
//! * [handlebars_templates](Template)
//! * [tera_templates](Template)
//! * [uuid](Uuid)
//! * [${database}_pool](databases)
//!
//! The recommend way to include features from this crate via Cargo in your
//! project is by adding a `[dependencies.rocket_contrib]` section to your
//! `Cargo.toml` file, setting `default-features` to false, and specifying
//! features manually. For example, to use the JSON module, you would add:
//!
//! ```toml,ignore
//! ```toml
//! [dependencies.rocket_contrib]
//! version = "*"
//! default-features = false

9
contrib/lib/src/templates/engine.rs
View File

@ -40,8 +40,8 @@ pub trait Engine: Send + Sync + 'static {
/// });
/// ```
///
/// [`tera::Value`]: https://docs.rs/tera/0.10.10/tera/enum.Value.html
/// [`tera::Result`]: https://docs.rs/tera/0.10.10/tera/type.Result.html
/// [`tera::Value`]: ::tera::Value
/// [`tera::Result`]: ::tera::Result
pub struct Engines {
#[cfg(feature = "tera_templates")]
/// A [`Tera`] structure. This field is only available when the
@ -49,15 +49,14 @@ pub struct Engines {
/// instance, ensure you use types imported from `rocket_contrib::tera` to
/// avoid version mismatches.
///
/// [`Tera`]: https://docs.rs/tera/0.10.10/tera/struct.Tera.html
/// [`Tera`]: tera::Tera
pub tera: Tera,
/// A [`Handlebars`] structure. This field is only available when the
/// `handlebars_templates` feature is enabled. When calling methods on the
/// `Tera` instance, ensure you use types
/// imported from `rocket_contrib::handlebars` to avoid version mismatches.
///
/// [`Handlebars`]:
/// https://docs.rs/handlebars/0.29.1/handlebars/struct.Handlebars.html
/// [`Handlebars`]: handlebars::Handlebars
#[cfg(feature = "handlebars_templates")]
pub handlebars: Handlebars,
}

8
contrib/lib/src/templates/metadata.rs
View File

@ -4,13 +4,13 @@ use rocket::request::{self, FromRequest};
use super::ContextManager;
/// The `TemplateMetadata` type: implements `FromRequest`, allowing dynamic
/// queries about template metadata.
/// Implements [`FromRequest`] for dynamiclly querying template metadata.
///
/// # Usage
///
/// First, ensure that the template [fairing](`rocket::fairing`),
/// [`Template::fairing()`] is attached to your Rocket application:
/// First, ensure that the template [fairing](rocket::fairing),
/// [`Template::fairing()`](::Template::fairing()) is attached to your Rocket
/// application:
///
/// ```rust
/// # extern crate rocket;

24
contrib/lib/src/templates/mod.rs
View File

@ -69,14 +69,13 @@ const DEFAULT_TEMPLATE_DIR: &str = "templates";
/// Template discovery is actualized by the template fairing, which itself is
/// created via the [`Template::fairing()`] or [`Template::custom()`] method. In
/// order for _any_ templates to be rendered, the template fairing _must_ be
/// [attached](/rocket/struct.Rocket.html#method.attach) to the running Rocket
/// instance. Failure to do so will result in an error.
/// [attached](rocket::Rocket::attach()) to the running Rocket instance. Failure
/// to do so will result in an error.
///
/// Templates are rendered with the `render` method. The method takes in the
/// name of a template and a context to render the template with. The context
/// can be any type that implements `Serialize` from
/// [Serde](https://github.com/serde-rs/json) and would serialize to an `Object`
/// value.
/// can be any type that implements [`Serialize`] from [`serde`] and would
/// serialize to an `Object` value.
///
/// In debug mode (without the `--release` flag passed to `cargo`), templates
/// will be automatically reloaded from disk if any changes have been made to
@ -89,15 +88,15 @@ const DEFAULT_TEMPLATE_DIR: &str = "templates";
/// feature, or both, to the `rocket_contrib` dependencies section of your
/// `Cargo.toml`:
///
/// ```toml,ignore
/// ```toml
/// [dependencies.rocket_contrib]
/// version = "*"
/// default-features = false
/// features = ["handlebars_templates", "tera_templates"]
/// ```
///
/// Then, ensure that the template [fairing](/rocket/fairing/) is attached to
/// your Rocket application:
/// Then, ensure that the template [`Fairing`] is attached to your Rocket
/// application:
///
/// ```rust
/// extern crate rocket;
@ -114,7 +113,7 @@ const DEFAULT_TEMPLATE_DIR: &str = "templates";
/// }
/// ```
///
/// The `Template` type implements Rocket's `Responder` trait, so it can be
/// The `Template` type implements Rocket's [`Responder`] trait, so it can be
/// returned from a request handler directly:
///
/// ```rust,ignore
@ -130,9 +129,6 @@ const DEFAULT_TEMPLATE_DIR: &str = "templates";
/// You can use the [`Template::custom()`] method to construct a fairing with
/// customized templating engines. Among other things, this method allows you to
/// register template helpers and register templates from strings.
///
/// [`Template::custom()`]: /rocket_contrib/struct.Template.html#method.custom
/// [`Template::fairing()`]: /rocket_contrib/struct.Template.html#method.fairing
#[derive(Debug)]
pub struct Template {
name: Cow<'static, str>,
@ -161,8 +157,6 @@ impl Template {
/// If you wish to customize the internal templating engines, use
/// [`Template::custom()`] instead.
///
/// [`Template::custom()`]: /rocket_contrib/struct.Template.html#method.custom
///
/// # Example
///
/// To attach this fairing, simple call `attach` on the application's
@ -192,8 +186,6 @@ impl Template {
/// templating engines via the parameter `f`. Note that only the enabled
/// templating engines will be accessible from the `Engines` type.
///
/// [`Template::fairing()`]: /rocket_contrib/struct.Template.html#method.fairing
///
/// # Example
///
/// ```rust

4
contrib/lib/src/uuid.rs
View File

@ -9,8 +9,8 @@ use rocket::http::RawStr;
pub use self::uuid_ext::parser::ParseError as UuidParseError;
/// Implements `FromParam` and `FormFormValue` for accepting UUID values from
/// the [uuid](https://github.com/rust-lang-nursery/uuid) crate.
/// Implements [`FromParam`] and [`FromFormValue`] for accepting UUID values
/// from the [`uuid`] crate.
///
/// # Usage
///

16
core/codegen_next/src/lib.rs
View File

@ -149,8 +149,8 @@
//! field name is expected. In this case, the `field` name in the attribute is
//! used instead of the structure's actual field name when parsing a form.
//!
//! [`FromForm`]: /rocket/request/trait.FromForm.html
//! [`FromFormValue`]: /rocket/request/trait.FromFormValue.html
//! [`FromForm`]: rocket::request::FromForm
//! [`FromFormValue`]: rocket::request::FromFormValue
//!
//! ### `FromFormValue`
//!
@ -306,9 +306,9 @@
//! The [`Response`] produced from the generated implementation will have its
//! content-type overriden to this value.
//!
//! [`Responder`]: /rocket/response/trait.Responder.html
//! [`Response`]: /rocket/struct.Response.html
//! [`Response::set_header()`]: /rocket/struct.Response.html#method.set_header
//! [`Responder`]: rocket::response::Responder
//! [`Response`]: rocket::Response
//! [`Response::set_header()`]: rocket::Response::set_header()
//!
//! ## Procedural Macros
//!
@ -404,9 +404,9 @@
//! If a mount-point is provided, the mount-point is prepended to the route's
//! URI.
//!
//! [`Uri`]: /rocket/http/uri/struct.URI.html
//! [`FromUriParam`]: /rocket/http/uri/trait.FromUriParam.html
//! [`UriDisplay`]: /rocket/http/uri/trait.UriDisplay.html
//! [`Uri`]: http::uri::URI
//! [`FromUriParam`]: http::uri::FromUriParam
//! [`UriDisplay`]: http::uri::UriDisplay
//!
//! # Debugging Codegen
//!

15
core/http/src/accept.rs
View File

@ -120,19 +120,18 @@ impl PartialEq for AcceptParams {
/// The HTTP Accept header.
///
/// An `Accept` header is composed of zero or more media types, each of which
/// may have an optional quality value (a [`QMediaType`]). The header is sent by an HTTP client to
/// describe the formats it accepts as well as the order in which it prefers
/// different formats.
/// may have an optional quality value (a [`QMediaType`]). The header is sent by
/// an HTTP client to describe the formats it accepts as well as the order in
/// which it prefers different formats.
///
/// # Usage
///
/// The Accept header of an incoming request can be retrieved via the
/// [`Request::accept`] method. The [`preferred`] method can be used to retrieve
/// the client's preferred media type.
/// [`Request::accept()`] method. The [`preferred()`] method can be used to
/// retrieve the client's preferred media type.
///
/// [`Request::accept`]: /rocket/struct.Request.html#method.accept
/// [`preferred`]: /rocket/http/struct.Accept.html#method.preferred
/// [`QMediaType`]: /rocket/http/struct.QMediaType.html
/// [`Request::accept`]: ::rocket::Request::accept()
/// [`preferred()`]: Accept::preferred()
///
/// An `Accept` type with a single, common media type can be easily constructed
/// via provided associated constants.

28
core/http/src/cookies.rs
View File

@ -16,18 +16,18 @@ use Header;
/// # Usage
///
/// A type of `Cookies` can be retrieved via its `FromRequest` implementation as
/// a request guard or via the [`Request::cookies`] method. Individual cookies
/// can be retrieved via the [`get`] and [`get_private`] methods. Cookies can be
/// added or removed via the [`add`], [`add_private`], [`remove`], and
/// [`remove_private`] methods.
/// a request guard or via the [`Request::cookies()`] method. Individual cookies
/// can be retrieved via the [`get()`] and [`get_private()`] methods. Cookies
/// can be added or removed via the [`add()`], [`add_private()`], [`remove()`],
/// and [`remove_private()`] methods.
///
/// [`get`]: /rocket/http/enum.Cookies.html#method.get
/// [`get_private`]: /rocket/http/enum.Cookies.html#method.get_private
/// [`add`]: /rocket/http/enum.Cookies.html#method.add
/// [`add_private`]: /rocket/http/enum.Cookies.html#method.add_private
/// [`remove`]: /rocket/http/enum.Cookies.html#method.remove
/// [`remove_private`]: /rocket/http/enum.Cookies.html#method.remove_private
/// [`Request::cookies`]: /rocket/struct.Request.html#method.cookies
/// [`Request::cookies()`]: ::rocket::Request::cookies()
/// [`get()`]: #method.get
/// [`get_private()`]: #method.get_private
/// [`add()`]: #method.add
/// [`add_private()`]: #method.add_private
/// [`remove()`]: #method.remove
/// [`remove_private()`]: #method.remove_private
///
/// ## Examples
///
@ -52,7 +52,7 @@ use Header;
/// as an integer, a `User` structure is validated. Otherwise, the guard
/// forwards.
///
/// [private cookie]: /rocket/http/enum.Cookies.html#private-cookies
/// [private cookie]: Cookies::add_private()
///
/// ```rust
/// # #![feature(proc_macro_hygiene, decl_macro, never_type)]
@ -89,8 +89,8 @@ use Header;
/// being signed and encrypted.
///
/// Private cookies can be retrieved, added, and removed from a `Cookies`
/// collection via the [`get_private`], [`add_private`], and [`remove_private`]
/// methods.
/// collection via the [`get_private()`], [`add_private()`], and
/// [`remove_private()`] methods.
///
/// ## Encryption Key
///

5
core/http/src/header.rs
View File

@ -17,9 +17,8 @@ pub struct Header<'h> {
impl<'h> Header<'h> {
/// Constructs a new header. This method should be used rarely and only for
/// non-standard headers. Instead, prefer to use the `Into<Header>`
/// implementations of many types, including
/// [ContentType](struct.ContentType.html) and all of the headers in
/// [http::hyper::header](hyper/header/index.html).
/// implementations of many types, including [`ContentType`] and all of the
/// headers in [`http::hyper::header`](hyper::header).
///
/// # Examples
///

6
core/http/src/lib.rs
View File

@ -8,9 +8,9 @@
//!
//! This module exports types that map to HTTP concepts or to the underlying
//! HTTP library when needed. Because the underlying HTTP library is likely to
//! change (see <a
//! href="https://github.com/SergioBenitez/Rocket/issues/17">#17</a>), types in
//! [hyper](hyper/index.html) should be considered unstable.
//! change (see [#17]), types in [`hyper`] should be considered unstable.
//!
//! [#17]: https://github.com/SergioBenitez/Rocket/issues/17
#[macro_use]
extern crate pear;

19
core/http/src/media_type.rs
View File

@ -62,19 +62,14 @@ impl Source {
/// A `MediaType` should rarely be used directly. Instead, one is typically used
/// indirectly via types like [`Accept`] and [`ContentType`], which internally
/// contain `MediaType`s. Nonetheless, a `MediaType` can be created via the
/// [`new`], [`with_params`], and [`from_extension`] methods. The preferred
/// method, however, is to create a `MediaType` via an associated constant.
///
/// [`Accept`]: /rocket/http/struct.Accept.html
/// [`ContentType`]: /rocket/http/struct.ContentType.html
/// [`new`]: /rocket/http/struct.MediaType.html#method.new
/// [`with_params`]: /rocket/http/struct.MediaType.html#method.with_params
/// [`from_extension`]: /rocket/http/struct.MediaType.html#method.from_extension
/// [`MediaType::new()`], [`MediaType::with_params()`], and
/// [`MediaType::from_extension`()] methods. The preferred method, however, is
/// to create a `MediaType` via an associated constant.
///
/// ## Example
///
/// A media type of `application/json` can be instantiated via the `JSON`
/// constant:
/// A media type of `application/json` can be instantiated via the
/// [`MediaType::JSON`] constant:
///
/// ```rust
/// # extern crate rocket;
@ -96,9 +91,7 @@ impl Source {
/// typically the comparison that is desired.
///
/// If an exact comparison is desired that takes into account parameters, the
/// [`exact_eq`] method can be used.
///
/// [`exact_eq`]: /rocket/http/struct.MediaType.html#method.exact_eq
/// [`exact_eq()`](MediaType::exact_eq()) method can be used.
#[derive(Debug, Clone)]
pub struct MediaType {
/// Storage for the entire media type string.

37
core/http/src/raw_str.rs
View File

@ -19,21 +19,26 @@ use uncased::UncasedStr;
/// An `&RawStr` should be converted into one of the validated string input
/// types through methods on `RawStr`. These methods are summarized below:
///
/// * **[`url_decode`]** - used to decode a raw string in a form value context
/// * **[`percent_decode`], [`percent_decode_lossy`]** - used to
/// percent-decode a raw string, typically in a URL context
/// * **[`html_escape`]** - used to decode a string for use in HTML templates
/// * **[`as_str`]** - used when the `RawStr` is known to be safe in the
/// context of its intended use. Use sparingly and with care!
/// * **[`as_uncased_str`]** - used when the `RawStr` is known to be safe in
/// the context of its intended, uncased use
/// * **[`url_decode()`]** - used to decode a raw string in a form value
/// context
/// * **[`percent_decode()`], [`percent_decode_lossy()`]** - used to
/// percent-decode a raw string, typically in a URL context
/// * **[`html_escape()`]** - used to decode a string for use in HTML
/// templates
/// * **[`as_str()`]** - used when the `RawStr` is known to be safe in the
/// context of its intended use. Use sparingly and with care!
/// * **[`as_uncased_str()`]** - used when the `RawStr` is known to be safe in
/// the context of its intended, uncased use
///
/// [`as_str`]: /rocket/http/struct.RawStr.html#method.as_str
/// [`as_uncased_str`]: /rocket/http/struct.RawStr.html#method.as_uncased_str
/// [`url_decode`]: /rocket/http/struct.RawStr.html#method.url_decode
/// [`html_escape`]: /rocket/http/struct.RawStr.html#method.html_escape
/// [`percent_decode`]: /rocket/http/struct.RawStr.html#method.percent_decode
/// [`percent_decode_lossy`]: /rocket/http/struct.RawStr.html#method.percent_decode_lossy
/// **Note:** Template engines like Tera and Handlebars all functions like
/// [`html_escape()`] on all rendered template outputs by default.
///
/// [`as_str()`]: RawStr::as_str()
/// [`as_uncased_str()`]: RawStr::as_uncased_str()
/// [`url_decode()`]: RawStr::url_decode()
/// [`html_escape()`]: RawStr::html_escape()
/// [`percent_decode()`]: RawStr::percent_decode()
/// [`percent_decode_lossy()`]: RawStr::percent_decode_lossy()
///
/// # Usage
///
@ -42,8 +47,8 @@ use uncased::UncasedStr;
/// encounter an `&RawStr` as a parameter via [`FromParam`] or as a form value
/// via [`FromFormValue`].
///
/// [`FromParam`]: /rocket/request/trait.FromParam.html
/// [`FromFormValue`]: /rocket/request/trait.FromFormValue.html
/// [`FromParam`]: ::rocket::request::FromParam
/// [`FromFormValue`]: ::rocket::request::FromFormValue
#[repr(transparent)]
#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct RawStr(str);

2
core/http/src/status.rs
View File

@ -95,7 +95,7 @@ pub struct Status {
macro_rules! ctrs {
($($code:expr, $code_str:expr, $name:ident => $reason:expr),+) => {
$(
#[doc="[Status](struct.Status.html) with code <b>"]
#[doc="[`Status`] with code <b>"]
#[doc=$code_str]
#[doc="</b> and reason <i>"]
#[doc=$reason]

26
core/http/src/uri/from_uri_param.rs
View File

@ -1,8 +1,9 @@
use std::path::{Path, PathBuf};
use {RawStr, uri::UriDisplay};
use RawStr;
use uri::UriDisplay;
/// Conversion trait for parameters used in `uri!` invocations.
/// Conversion trait for parameters used in [`uri!`] invocations.
///
/// This trait is invoked once per expression passed into a [`uri!`] invocation.
/// In particular, for a route URI parameter of type `T` and a user-supplied
@ -19,16 +20,15 @@ use {RawStr, uri::UriDisplay};
/// impl<'a> FromUriParam<&'a str> for String { type Target = &'a str; }
/// ```
///
/// Because the `Target` type is the same as the input type, the conversion is a
/// no-op and free of cost, allowing an `&str` to be used in place of a
/// `String` without penalty. A similar no-op conversion exists for [`&RawStr`]:
/// Because the [`FromUriParam::Target`] type is the same as the input type, the
/// conversion is a no-op and free of cost, allowing an `&str` to be used in
/// place of a `String` without penalty. A similar no-op conversion exists for
/// [`&RawStr`](RawStr):
///
/// ```rust,ignore
/// impl<'a, 'b> FromUriParam<&'a str> for &'b RawStr { type Target = &'a str; }
/// ```
///
/// [`&RawStr`]: /rocket/http/struct.RawStr.html
///
/// # Implementing
///
/// Rocket provides a blanket implementation for all types that implement
@ -46,8 +46,8 @@ use {RawStr, uri::UriDisplay};
/// case, it's desirable to allow an `&str` to be used in place of a `String`.
///
/// When implementing `FromUriParam`, be aware that Rocket will use the
/// [`UriDisplay`] implementation of `Target`, _not_ of the source type.
/// Incorrect implementations can result in creating unsafe URIs.
/// [`UriDisplay`] implementation of [`FromUriParam::Target`], _not_ of the
/// source type. Incorrect implementations can result in creating unsafe URIs.
///
/// # Example
///
@ -96,16 +96,16 @@ use {RawStr, uri::UriDisplay};
/// // => "/hey?name=Robert+Mike&nickname=Bob"
/// ```
///
/// [`uri!`]: /rocket_codegen/#typed-uris-uri
/// [`UriDisplay`]: /rocket/http/uri/trait.UriDisplay.html
/// [`uri!`]: ::rocket_codegen::uri
/// [`UriDisplay`]: uri::UriDisplay
/// [`FromUriParam::Target`]: uri::FromUriParam::Target
pub trait FromUriParam<T> {
/// The resulting type of this conversion.
type Target: UriDisplay;
/// Converts a value of type `T` into a value of type `Self::Target`. The
/// resulting value of type `Self::Target` will be rendered into a URI using
/// its [`UriDisplay`](/rocket/http/uri/trait.UriDisplay.html)
/// implementation.
/// its [`UriDisplay`](uri::UriDisplay) implementation.
fn from_uri_param(param: T) -> Self::Target;
}

10
core/http/src/uri/origin.rs
View File

@ -63,8 +63,8 @@ use state::Storage;
/// # }
/// ```
///
/// The [`Origin::to_normalized()`] method can be used to normalize any
/// `Origin`:
/// The [`Origin::to_normalized()`](uri::Origin::to_normalized()) method can be
/// used to normalize any `Origin`:
///
/// ```rust
/// # extern crate rocket;
@ -178,9 +178,9 @@ impl<'a> Origin<'a> {
}
/// Parses the string `string` into an `Origin`. Parsing will never
/// allocate. This method should be used instead of [`Origin::parse()`] when
/// the source URI is already a `String`. Returns an `Error` if `string` is
/// not a valid origin URI.
/// allocate. This method should be used instead of
/// [`Origin::parse()`](uri::Origin::parse()) when the source URI is already
/// a `String`. Returns an `Error` if `string` is not a valid origin URI.
///
/// # Example
///

20
core/http/src/uri/uri.rs
View File

@ -18,7 +18,7 @@ use uri::{Origin, Authority, Absolute, Error};
///
/// Nevertheless, the `Uri` type is typically enountered as a conversion target.
/// In particular, you will likely see generic bounds of the form: `T:
/// TryInto<Uri>` (for instance, in [`Redirect`](rocket::response::Redirect)
/// TryInto<Uri>` (for instance, in [`Redirect`](::rocket::response::Redirect)
/// methods). This means that you can provide any type `T` that implements
/// `TryInto<Uri>`, or, equivalently, any type `U` for which `Uri` implements
/// `TryFrom<U>` or `From<U>`. These include `&str` and `String`, [`Origin`],
@ -37,15 +37,23 @@ use uri::{Origin, Authority, Absolute, Error};
/// ## Percent Encoding/Decoding
///
/// This type also provides the following percent encoding/decoding helper
/// methods: [`Uri::percent_encode`], [`Uri::percent_decode`], and
/// [`Uri::percent_decode_lossy`].
/// methods: [`Uri::percent_encode()`], [`Uri::percent_decode()`], and
/// [`Uri::percent_decode_lossy()`].
///
/// [`Origin`]: uri::Origin
/// [`Authority`]: uri::Authority
/// [`Absolute`]: uri::Absolute
/// [`Uri::parse()`]: uri::Uri::parse()
/// [`Uri::percent_encode()`]: uri::Uri::percent_encode()
/// [`Uri::percent_decode()`]: uri::Uri::percent_decode()
/// [`Uri::percent_decode_lossy()`]: uri::Uri::percent_decode_lossy()
#[derive(Debug, PartialEq, Clone)]
pub enum Uri<'a> {
/// An [`Origin`] URI.
/// An origin URI.
Origin(Origin<'a>),
/// An [`Authority`] URI.
/// An authority URI.
Authority(Authority<'a>),
/// An [`Absolute`] URI.
/// An absolute URI.
Absolute(Absolute<'a>),
/// An asterisk: exactly `*`.
Asterisk,

15
core/http/src/uri/uri_display.rs
View File

@ -74,7 +74,7 @@ use self::priv_encode_set::PATH_ENCODE_SET;
/// The implementation of `UriDisplay` for these types is identical to the
/// `Display` implementation.
///
/// * **[`&RawStr`](/rocket/http/struct.RawStr.html), `String`, `&str`,
/// * **[`&RawStr`](RawStr), `String`, `&str`,
/// `Cow<str>`**
///
/// The string is percent encoded.
@ -85,16 +85,17 @@ use self::priv_encode_set::PATH_ENCODE_SET;
///
/// # Implementing
///
/// Implementing `UriDisplay` is similar to implementing `Display` with the
/// caveat that extra care must be taken to ensure that the written string is
/// URI-safe. As mentioned before, in practice, this means that the string must
/// either be percent-encoded or consist only of characters that are
/// alphanumeric, "-", ".", "_", or "~".
/// Implementing `UriDisplay` is similar to implementing
/// [`Display`](::std::fmt::Display) with the caveat that extra care must be
/// taken to ensure that the written string is URI-safe. As mentioned before, in
/// practice, this means that the string must either be percent-encoded or
/// consist only of characters that are alphanumeric, "-", ".", "_", or "~".
///
/// When manually implementing `UriDisplay` for your types, you should defer to
/// existing implementations of `UriDisplay` as much as possible. In the example
/// below, for instance, `Name`'s implementation defers to `String`'s
/// implementation. To percent-encode a string, use [`Uri::percent_encode()`].
/// implementation. To percent-encode a string, use
/// [`Uri::percent_encode()`](uri::Uri::percent_encode()).
///
/// ## Example
///

7
core/lib/src/catcher.rs
View File

@ -10,8 +10,9 @@ use yansi::Color::*;
///
/// Catchers are routes that run when errors occur. They correspond directly
/// with the HTTP error status code they will be handling and are registered
/// with Rocket via the [`Rocket::register()`] method. For example, to handle
/// "404 not found" errors, a catcher for the "404" status code is registered.
/// with Rocket via [`Rocket::register()`](::Rocket::register()). For example,
/// to handle "404 not found" errors, a catcher for the "404" status code is
/// registered.
///
/// Because error handlers are only called when all routes are exhausted, they
/// should not fail nor forward. If an error catcher fails, the user will
@ -57,7 +58,7 @@ use yansi::Color::*;
/// ```
///
/// A function decorated with `catch` must take exactly zero or one arguments.
/// If the catcher takes an argument, it must be of type `&Request`.
/// If the catcher takes an argument, it must be of type [`&Request`](Request).
pub struct Catcher {
/// The HTTP status code to match against.
pub code: u16,

3
core/lib/src/config/builder.rs
View File

@ -35,8 +35,7 @@ impl ConfigBuilder {
/// the given `environment`. The root configuration directory is set to the
/// current working directory.
///
/// This method is typically called indirectly via
/// [Config::build](/rocket/config/struct.Config.html#method.build).
/// This method is typically called indirectly via [`Config::build()`].
///
/// # Panics
///

20
core/lib/src/config/config.rs
View File

@ -16,9 +16,8 @@ use http::Key;
///
/// # Usage
///
/// A `Config` structure is typically built using the [build](#method.build)
/// method and [ConfigBuilder](/rocket/config/struct.ConfigBuilder.html)
/// methods:
/// A `Config` structure is typically built using [`Config::build()`] and
/// builder methods on the returned [`ConfigBuilder`] structure:
///
/// ```rust
/// use rocket::config::{Config, Environment};
@ -33,10 +32,8 @@ use http::Key;
///
/// ## General Configuration
///
/// For more information about Rocket's configuration, see the [`config`] module
/// documentation.
///
/// [`config`]: /rocket/config/index.html
/// For more information about Rocket's configuration, see the
/// [`config`](::config) module documentation.
#[derive(Clone)]
pub struct Config {
/// The environment that this configuration corresponds to.
@ -909,11 +906,10 @@ impl Config {
}
}
/// If `path` is a relative path, `path` is appended to the [`root`] at
/// which the configuration file for `self` is stored and the new path is
/// returned. If `path` is absolute, `path` is returned unaltered.
///
/// [`root`]: /rocket/struct.Config.html#method.root
/// If `path` is a relative path, `path` is appended to the
/// [`Config::root()`] at which the configuration file for `self` is stored
/// and the new path is returned. If `path` is absolute, `path` is returned
/// unaltered.
///
/// # Example
///

3
core/lib/src/config/custom_values.rs
View File

@ -59,8 +59,7 @@ pub struct TlsConfig;
///
/// # Defaults
///
/// As documented in the [config module](/rocket/config/), the default limits
/// are as follows:
/// As documented in [`config`](::config), the default limits are as follows:
///
/// * **forms**: 32KiB
///

38
core/lib/src/config/mod.rs
View File

@ -31,30 +31,30 @@
//! not used by Rocket itself but can be used by external libraries. The
//! standard configuration parameters are:
//!
//! * **address**: _[string]_ an IP address or host the application will
//! * **address**: _string_ an IP address or host the application will
//! listen on
//! * examples: `"localhost"`, `"0.0.0.0"`, `"1.2.3.4"`
//! * **port**: _[integer]_ a port number to listen on
//! * **port**: _integer_ a port number to listen on
//! * examples: `"8000"`, `"80"`, `"4242"`
//! * **workers**: _[integer]_ the number of concurrent workers to use
//! * **workers**: _integer_ the number of concurrent workers to use
//! * examples: `12`, `1`, `4`
//! * **keep_alive**: _[integer, 'false', or 'none']_ timeout, in seconds, for
//! * **keep_alive**: _integer, 'false', or 'none'_ timeout, in seconds, for
//! HTTP keep-alive. disabled on 'false' or 'none'
//! * examples: `5`, `60`, `false`, `"none"`
//! * **log**: _[string]_ how much information to log; one of `"off"`,
//! * **log**: _string_ how much information to log; one of `"off"`,
//! `"normal"`, `"debug"`, or `"critical"`
//! * **secret_key**: _[string]_ a 256-bit base64 encoded string (44
//! * **secret_key**: _string_ a 256-bit base64 encoded string (44
//! characters) to use as the secret key
//! * example: `"8Xui8SN4mI+7egV/9dlfYYLGQJeEx4+DwmSQLwDVXJg="`
//! * **tls**: _[table]_ a table with two keys:
//! 1. `certs`: _[string]_ a path to a certificate chain in PEM format
//! 2. `key`: _[string]_ a path to a private key file in PEM format for the
//! * **tls**: _table_ a table with two keys:
//! 1. `certs`: _string_ a path to a certificate chain in PEM format
//! 2. `key`: _string_ a path to a private key file in PEM format for the
//! certificate in `certs`
//!
//! * example: `{ certs = "/path/to/certs.pem", key = "/path/to/key.pem" }`
//! * **limits**: _[table]_ a table where each key (_[string]_) corresponds to
//! a data type and the value (_[u64]_) corresponds to the maximum size in
//! bytes Rocket should accept for that type.
//! * **limits**: _table_ a table where each key (_string_) corresponds to a
//! data type and the value (`u64`) corresponds to the maximum size in bytes
//! Rocket should accept for that type.
//! * example: `{ forms = 65536 }` (maximum form size to 64KiB)
//!
//! ### Rocket.toml
@ -166,14 +166,13 @@
//! ## Retrieving Configuration Parameters
//!
//! Configuration parameters for the currently active configuration environment
//! can be retrieved via the [config](/rocket/struct.Rocket.html#method.config)
//! method on an instance of `Rocket` and `get_` methods on the
//! [Config](struct.Config.html) structure.
//! can be retrieved via the [`Rocket::config()`] `Rocket` and `get_` methods on
//! [`Config`] structure.
//!
//! The retrivial of configuration parameters usually occurs at launch time via
//! a [launch fairing](/rocket/fairing/trait.Fairing.html). If information about
//! the configuraiton is needed later in the program, an attach fairing can be
//! used to store the information as managed state. As an example of the latter,
//! a [launch fairing](::fairing::Fairing). If information about the
//! configuraiton is needed later in the program, an attach fairing can be used
//! to store the information as managed state. As an example of the latter,
//! consider the following short program which reads the `token` configuration
//! parameter and stores the value or a default in a `Token` managed state
//! value:
@ -230,8 +229,7 @@ const GLOBAL_ENV_NAME: &str = "global";
const ENV_VAR_PREFIX: &str = "ROCKET_";
const PREHANDLED_VARS: [&str; 2] = ["ROCKET_CODEGEN_DEBUG", CONFIG_ENV];
/// Wraps `std::result` with the error type of
/// [ConfigError](enum.ConfigError.html).
/// Wraps `std::result` with the error type of [`ConfigError`].
pub type Result<T> = ::std::result::Result<T, ConfigError>;
#[doc(hidden)]

6
core/lib/src/data/data.rs
View File

@ -27,8 +27,8 @@ const PEEK_BYTES: usize = 512;
///
/// This type is the only means by which the body of a request can be retrieved.
/// This type is not usually used directly. Instead, types that implement
/// [`FromData`] are used via code generation by specifying the `data = "<var>"`
/// route parameter as follows:
/// [`FromData`](::data::Data) are used via code generation by specifying the
/// `data = "<var>"` route parameter as follows:
///
/// ```rust
/// # #![feature(proc_macro_hygiene, decl_macro)]
@ -45,7 +45,7 @@ const PEEK_BYTES: usize = 512;
/// # Reading Data
///
/// Data may be read from a `Data` object by calling either the
/// [open](#method.open) or [peek](#method.peek) methods.
/// [`open()`](Data::open()) or [`peek()`](Data::peek()) methods.
///
/// The `open` method consumes the `Data` object and returns the raw data
/// stream. The `Data` object is consumed for safety reasons: consuming the

6
core/lib/src/data/data_stream.rs
View File

@ -11,9 +11,9 @@ pub type InnerStream = Chain<Cursor<Vec<u8>>, BodyReader>;
/// Raw data stream of a request body.
///
/// This stream can only be obtained by calling
/// [Data::open](/rocket/data/struct.Data.html#method.open). The stream contains
/// all of the data in the body of the request. It exposes no methods directly.
/// Instead, it must be used as an opaque `Read` structure.
/// [`Data::open()`](::data::Data::open()). The stream contains all of the data
/// in the body of the request. It exposes no methods directly. Instead, it must
/// be used as an opaque [`Read`] structure.
pub struct DataStream(crate InnerStream);
// TODO: Have a `BufRead` impl for `DataStream`. At the moment, this isn't

22
core/lib/src/data/from_data.rs
View File

@ -120,7 +120,7 @@ pub type Transformed<'a, T> =
/// Data guards are used as the target of the `data` route attribute parameter.
/// A handler can have at most one data guard.
///
/// [request guard]: /rocket/request/trait.FromRequest.html
/// [request guard]: ::request::FromRequest
///
/// ## Example
///
@ -235,26 +235,26 @@ pub type Transformed<'a, T> =
///
/// # Outcomes
///
/// The returned [Outcome](/rocket/outcome/index.html) of a `from_data` call
/// determines how the incoming request will be processed.
/// The returned [`Outcome`] of a `from_data` call determines how the incoming
/// request will be processed.
///
/// * **Success**(S)
///
/// If the `Outcome` is `Success`, then the `Success` value will be used as
/// If the `Outcome` is [`Success`], then the `Success` value will be used as
/// the value for the data parameter. As long as all other parsed types
/// succeed, the request will be handled by the requesting handler.
///
/// * **Failure**(Status, E)
///
/// If the `Outcome` is `Failure`, the request will fail with the given status
/// code and error. The designated error
/// [Catcher](/rocket/struct.Catcher.html) will be used to respond to the
/// request. Note that users can request types of `Result<S, E>` and
/// `Option<S>` to catch `Failure`s and retrieve the error value.
/// If the `Outcome` is [`Failure`], the request will fail with the given
/// status code and error. The designated error [`Catcher`](::Catcher) will be
/// used to respond to the request. Note that users can request types of
/// `Result<S, E>` and `Option<S>` to catch `Failure`s and retrieve the error
/// value.
///
/// * **Forward**(Data)
///
/// If the `Outcome` is `Forward`, the request will be forwarded to the next
/// If the `Outcome` is [`Forward`], the request will be forwarded to the next
/// matching request. This requires that no data has been read from the `Data`
/// parameter. Note that users can request an `Option<S>` to catch `Forward`s.
///
@ -265,7 +265,7 @@ pub type Transformed<'a, T> =
///
/// * **Data**
///
/// The identity implementation; simply returns `Data` directly.
/// The identity implementation; simply returns [`Data`] directly.
///
/// _This implementation always returns successfully._
///

5
core/lib/src/error.rs
View File

@ -27,9 +27,8 @@ pub enum LaunchErrorKind {
/// An error that occurs during launch.
///
/// A `LaunchError` is returned by
/// [rocket::launch](/rocket/struct.Rocket.html#method.launch) when launching an
/// application fails for some reason.
/// A `LaunchError` is returned by [`launch()`](::Rocket::launch()) when
/// launching an application fails.
///
/// # Panics
///

10
core/lib/src/fairing/info_kind.rs
View File

@ -1,11 +1,11 @@
use std::ops::BitOr;
/// Information about a [`Fairing`](/rocket/fairing/trait.Fairing.html).
/// Information about a [`Fairing`](::fairing::Fairing).
///
/// The `name` field is an arbitrary name for a fairing. The `kind` field is a
/// is an `or`d set of [`Kind`](/rocket/fairing/struct.Kind.html) structures.
/// Rocket uses the values set in `Kind` to determine which callbacks from a
/// given `Fairing` implementation to actually call.
/// is an `or`d set of [`Kind`] structures. Rocket uses the values set in `Kind`
/// to determine which callbacks from a given `Fairing` implementation to
/// actually call.
///
/// # Example
///
@ -30,7 +30,7 @@ pub struct Info {
}
/// A bitset representing the kinds of callbacks a
/// [`Fairing`](/rocket/fairing/trait.Fairing.html) wishes to receive.
/// [`Fairing`](::fairing::Fairing) wishes to receive.
///
/// A fairing can request any combination of any of the following kinds of
/// callbacks:

125
core/lib/src/fairing/mod.rs
View File

@ -8,18 +8,16 @@
//! to perform an action once a Rocket application has launched.
//!
//! To learn more about writing a fairing, see the [`Fairing`] trait
//! documentation. You can also use [`AdHoc`] to create a fairing on-the-fly
//! from a closure or function.
//!
//! [`AdHoc`]: /rocket/fairing/enum.AdHoc.html
//! documentation. You can also use [`AdHoc`](fairing::AdHoc) to create a
//! fairing on-the-fly from a closure or function.
//!
//! ## Attaching
//!
//! You must inform Rocket about fairings that you wish to be active by calling
//! the [`attach`](/rocket/struct.Rocket.html#method.attach) method on the
//! [`Rocket`](/rocket/struct.Rocket.html) instance and passing in the
//! appropriate [`Fairing`]. For instance, to attach fairings named
//! `req_fairing` and `res_fairing` to a new Rocket instance, you might write:
//! [`Rocket::attach()`] method on the application's [`Rocket`] instance and
//! passing in the appropriate [`Fairing`]. For instance, to attach fairings
//! named `req_fairing` and `res_fairing` to a new Rocket instance, you might
//! write:
//!
//! ```rust
//! # use rocket::fairing::AdHoc;
@ -35,7 +33,7 @@
//! trait documentation for more information on the dispatching of fairing
//! methods.
//!
//! [`Fairing`]: /rocket/fairing/trait.Fairing.html
//! [`Fairing`]: ::fairing::Fairing
//!
//! ## Ordering
//!
@ -90,9 +88,9 @@ pub use self::info_kind::{Info, Kind};
/// entire application. On the other hand, you _should_ use a fairing to record
/// timing and/or usage statistics or to implement global security policies.
///
/// [request guard]: /rocket/request/trait.FromRequest.html
/// [request guards]: /rocket/request/trait.FromRequest.html
/// [data guards]: /rocket/data/trait.FromData.html
/// [request guard]: ::request::FromRequest
/// [request guards]: ::request::FromRequest
/// [data guards]: ::data::FromData
///
/// ## Fairing Callbacks
///
@ -105,13 +103,12 @@ pub use self::info_kind::{Info, Kind};
///
/// * **Attach (`on_attach`)**
///
/// An attach callback, represented by the
/// [`on_attach`](/rocket/fairing/trait.Fairing.html#method.on_attach)
/// method, is called when a fairing is first attached via the
/// [`attach`](/rocket/struct.Rocket.html#method.attach) method. The state
/// of the `Rocket` instance is, at this point, not finalized, as the user
/// may still add additional information to the `Rocket` instance. As a
/// result, it is unwise to depend on the state of the `Rocket` instance.
/// An attach callback, represented by the [`Fairing::on_attach()`] method,
/// is called when a fairing is first attached via [`Rocket::attach()`]
/// method. The state of the `Rocket` instance is, at this point, not
/// finalized, as the user may still add additional information to the
/// `Rocket` instance. As a result, it is unwise to depend on the state of
/// the `Rocket` instance.
///
/// An attach callback can arbitrarily modify the `Rocket` instance being
/// constructed. It returns `Ok` if it would like launching to proceed
@ -121,43 +118,39 @@ pub use self::info_kind::{Info, Kind};
///
/// * **Launch (`on_launch`)**
///
/// A launch callback, represented by the
/// [`on_launch`](/rocket/fairing/trait.Fairing.html#method.on_launch)
/// method, is called immediately before the Rocket application has
/// launched. At this point, Rocket has opened a socket for listening but
/// has not yet begun accepting connections. A launch callback can inspect
/// the `Rocket` instance being launched.
/// A launch callback, represented by the [`Fairing::on_launch()`] method,
/// is called immediately before the Rocket application has launched. At
/// this point, Rocket has opened a socket for listening but has not yet
/// begun accepting connections. A launch callback can inspect the `Rocket`
/// instance being launched.
///
/// * **Request (`on_request`)**
///
/// A request callback, represented by the
/// [`on_request`](/rocket/fairing/trait.Fairing.html#method.on_request)
/// method, is called just after a request is received, immediately after
/// A request callback, represented by the [`Fairing::on_request()`] method,
/// is called just after a request is received, immediately after
/// pre-processing the request with method changes due to `_method` form
/// fields. At this point, Rocket has parsed the incoming HTTP request into
/// [`Request`](/rocket/struct.Request.html) and
/// [`Data`](/rocket/struct.Data.html) structures but has not routed the
/// request. A request callback can modify the request at will and
/// [`peek`](/rocket/struct.Data.html#method.peek) into the incoming data.
/// It may not, however, abort or respond directly to the request; these
/// issues are better handled via [request
/// guards](/rocket/request/trait.FromRequest.html) or via response
/// callbacks. Any modifications to a request are persisted and can
/// potentially alter how a request is routed.
///
/// [`Request`] and [`Data`] structures but has not routed the request. A
/// request callback can modify the request at will and [`Data::peek()`]
/// into the incoming data. It may not, however, abort or respond directly
/// to the request; these issues are better handled via [request guards] or
/// via response callbacks. Any modifications to a request are persisted and
/// can potentially alter how a request is routed.
///=
/// * **Response (`on_response`)**
///
/// A response callback is called when a response is ready to be sent to the
/// client. At this point, Rocket has completed all routing, including to
/// error catchers, and has generated the would-be final response. A
/// response callback can modify the response at will. For example, a
/// response callback can provide a default response when the user fails to
/// handle the request by checking for 404 responses. Note that a given
/// `Request` may have changed between `on_request` and `on_response`
/// invocations. Apart from any change made by other fairings, Rocket sets
/// the method for `HEAD` requests to `GET` if there is no matching `HEAD`
/// handler for that request. Additionally, Rocket will automatically strip
/// the body for `HEAD` requests _after_ response fairings have run.
/// A response callback, represented by the [`Fairing::on_response()`]
/// method, is called when a response is ready to be sent to the client. At
/// this point, Rocket has completed all routing, including to error
/// catchers, and has generated the would-be final response. A response
/// callback can modify the response at will. For example, a response
/// callback can provide a default response when the user fails to handle
/// the request by checking for 404 responses. Note that a given `Request`
/// may have changed between `on_request` and `on_response` invocations.
/// Apart from any change made by other fairings, Rocket sets the method for
/// `HEAD` requests to `GET` if there is no matching `HEAD` handler for that
/// request. Additionally, Rocket will automatically strip the body for
/// `HEAD` requests _after_ response fairings have run.
///
/// # Implementing
///
@ -170,8 +163,7 @@ pub use self::info_kind::{Info, Kind};
/// ## Fairing `Info`
///
/// Every `Fairing` must implement the [`info`] method, which returns an
/// [`Info`](/rocket/fairing/struct.Info.html) structure. This structure is used
/// by Rocket to:
/// [`Info`] structure. This structure is used by Rocket to:
///
/// 1. Assign a name to the `Fairing`.
///
@ -181,32 +173,30 @@ pub use self::info_kind::{Info, Kind};
///
/// 2. Determine which callbacks to actually issue on the `Fairing`.
///
/// This is the `kind` field of type
/// [`Kind`](/rocket/fairing/struct.Kind.html). This field is a bitset that
/// This is the `kind` field of type [`Kind`]. This field is a bitset that
/// represents the kinds of callbacks the fairing wishes to receive. Rocket
/// will only invoke the callbacks that are flagged in this set. `Kind`
/// structures can be `or`d together to represent any combination of kinds
/// of callbacks. For instance, to request launch and response callbacks,
/// return a `kind` field with the value `Kind::Launch | Kind::Response`.
///
/// [`info`]: /rocket/fairing/trait.Fairing.html#tymethod.info
/// [`info`]: Fairing::info()
///
/// ## Restrictions
///
/// A `Fairing` must be `Send + Sync + 'static`. This means that the fairing
/// must be sendable across thread boundaries (`Send`), thread-safe (`Sync`),
/// and have only `'static` references, if any (`'static`). Note that these
/// bounds _do not_ prohibit a `Fairing` from holding state: the state need
/// simply be thread-safe and statically available or heap allocated.
/// A `Fairing` must be [`Send`] + [`Sync`] + `'static`. This means that the
/// fairing must be sendable across thread boundaries (`Send`), thread-safe
/// (`Sync`), and have only `'static` references, if any (`'static`). Note that
/// these bounds _do not_ prohibit a `Fairing` from holding state: the state
/// need simply be thread-safe and statically available or heap allocated.
///
/// ## Example
///
/// Imagine that we want to record the number of `GET` and `POST` requests that
/// our application has received. While we could do this with [request
/// guards](/rocket/request/trait.FromRequest.html) and [managed
/// state](/rocket/request/struct.State.html), it would require us to annotate
/// every `GET` and `POST` request with custom types, polluting handler
/// signatures. Instead, we can create a simple fairing that acts globally.
/// our application has received. While we could do this with [request guards]
/// and [managed state](::request::State), it would require us to annotate every
/// `GET` and `POST` request with custom types, polluting handler signatures.
/// Instead, we can create a simple fairing that acts globally.
///
/// The `Counter` fairing below records the number of all `GET` and `POST`
/// requests received. It makes these counts available at a special `'/counts'`
@ -333,10 +323,9 @@ pub use self::info_kind::{Info, Kind};
/// [request-local state]: https://rocket.rs/guide/state/#request-local-state
pub trait Fairing: Send + Sync + 'static {
/// Returns an [`Info`](/rocket/fairing/struct.Info.html) structure
/// containing the `name` and [`Kind`](/rocket/fairing/struct.Kind.html) of
/// this fairing. The `name` can be any arbitrary string. `Kind` must be an
/// `or`d set of `Kind` variants.
/// Returns an [`Info`] structure containing the `name` and [`Kind`] of this
/// fairing. The `name` can be any arbitrary string. `Kind` must be an `or`d
/// set of `Kind` variants.
///
/// This is the only required method of a `Fairing`. All other methods have
/// no-op default implementations.

65
core/lib/src/lib.rs
View File

@ -12,54 +12,51 @@
// TODO: Version URLs.
#![doc(html_root_url = "https://api.rocket.rs")]
#![doc(html_favicon_url = "https://rocket.rs/favicon.ico")]
#![doc(html_logo_url = "https://rocket.rs/images/logo-boxed.png")]
//! # Rocket - Core API Documentation
//!
//! Hello, and welcome to the core Rocket API documentation!
//!
//! This API documentation is highly technical and is purely a reference.
//! There's an [overview](https://rocket.rs/overview) of Rocket on the main site
//! as well as a [full, detailed guide](https://rocket.rs/guide). If you'd like
//! pointers on getting started, see the
//! [quickstart](https://rocket.rs/guide/quickstart) or [getting
//! started](https://rocket.rs/guide/getting-started) chapters of the guide.
//! There's an [overview] of Rocket on the main site as well as a [full,
//! detailed guide]. If you'd like pointers on getting started, see the
//! [quickstart] or [getting started] chapters of the guide.
//!
//! You may also be interested in looking at the [contrib API
//! documentation](/rocket_contrib), which contains JSON and templating
//! support, among other features.
//! You may also be interested in looking at the [`rocket_contrib`]
//! documentation, which contains automatic JSON (de)serialiazation, templating
//! support, static file serving, and other useful features.
//!
//! [overview]: https://rocket.rs/overview
//! [full, detailed guide]: https://rocket.rs/guide
//! [quickstart]: https://rocket.rs/guide/quickstart
//! [getting started]: https://rocket.rs/guide/getting-started
//!
//! ## Libraries
//!
//! Rocket's functionality is split into two crates:
//!
//! 1. [Core](/rocket) - The core library. Needed by every Rocket application.
//! 2. [Contrib](/rocket_contrib) - Provides useful functionality for many
//! 1. Core - This core library. Needed by every Rocket application.
//! 2. [Contrib](rocket_contrib) - Provides useful functionality for many
//! Rocket applications. Completely optional.
//!
//! ## Usage
//!
//! The sanctioned way to use Rocket is via the code generation plugin. This
//! makes Rocket easier and safer to use and allows a somewhat stable API as
//! Rocket matures. To use Rocket with the code generation plugin in your
//! Cargo-based project, add the following to `Cargo.toml`:
//! First, depend on `rocket` in `Cargo.toml`:
//!
//! ```rust,ignore
//! ```toml
//! [dependencies]
//! rocket = "*"
//! rocket = "0.4.0-dev"
//! ```
//!
//! If you'll be deploying your project to [crates.io](https://crates.io),
//! you'll need to change the "*" to the current version of Rocket.
//!
//! Then, add the following to the top of your `main.rs` file:
//!
//! ```rust
//! #![feature(proc_macro_hygiene, decl_macro)]
//!
//! #[macro_use] extern crate rocket;
//! #
//! # #[get("/")]
//! # fn hello() { }
//! # #[get("/")] fn hello() { }
//! # fn main() { rocket::ignite().mount("/", routes![hello]); }
//! ```
//!
@ -87,16 +84,19 @@
//!
//! Rocket and Rocket libraries are configured via the `Rocket.toml` file and/or
//! `ROCKET_{PARAM}` environment variables. For more information on how to
//! configure Rocket, see the [configuration
//! section](https://rocket.rs/guide/configuration/) of the guide as well as the
//! [config](/rocket/config) module documentation.
//! configure Rocket, see the [configuration section] of the guide as well as
//! the [`config`] module documentation.
//!
//! [configuration section]: https://rocket.rs/guide/configuration/
//!
//! ## Testing
//!
//! The [local](/rocket/local) module contains structures that facilitate unit
//! and integration testing of a Rocket application. The [top-level `local`
//! module documentation](/rocket/local) and the [testing chapter of the
//! guide](https://rocket.rs/guide/testing/#testing) include detailed examples.
//! The [`local`] module contains structures that facilitate unit and
//! integration testing of a Rocket application. The top-level [`local`] module
//! documentation and the [testing chapter of the guide] include detailed
//! examples.
//!
//! [testing chapter of the guide]: https://rocket.rs/guide/testing/#testing
#[allow(unused_imports)] #[macro_use] extern crate rocket_codegen_next;
#[doc(hidden)] pub use rocket_codegen_next::*;
@ -154,14 +154,13 @@ pub use request::{Request, State};
pub use catcher::Catcher;
pub use rocket::Rocket;
/// Alias to [Rocket::ignite()](/rocket/struct.Rocket.html#method.ignite).
/// Creates a new instance of `Rocket`.
/// Alias to [`Rocket::ignite()`] Creates a new instance of `Rocket`.
pub fn ignite() -> Rocket {
Rocket::ignite()
}
/// Alias to [Rocket::custom()](/rocket/struct.Rocket.html#method.custom).
/// Creates a new instance of `Rocket` with a custom configuration.
/// Alias to [`Rocket::custom()`]. Creates a new instance of `Rocket` with a
/// custom configuration.
pub fn custom(config: config::Config) -> Rocket {
Rocket::custom(config)
}

44
core/lib/src/local/client.rs
View File

@ -15,8 +15,7 @@ use error::LaunchError;
/// constructed, the [`LocalRequest`] constructor methods ([`get`], [`put`],
/// [`post`], and so on) can be used to create a `LocalRequest` for dispatching.
///
/// See the [top-level documentation](/rocket/local/index.html) for more usage
/// information.
/// See the [top-level documentation](::local) for more usage information.
///
/// ## Cookie Tracking
///
@ -49,7 +48,6 @@ use error::LaunchError;
///
/// [`new`]: #method.new
/// [`untracked`]: #method.untracked
/// [`LocalRequest`]: /rocket/local/struct.LocalRequest.html
/// [`get`]: #method.get
/// [`put`]: #method.put
/// [`post`]: #method.post
@ -152,9 +150,8 @@ impl Client {
///
/// When dispatched, the request will be served by the instance of Rocket
/// within `self`. The request is not dispatched automatically. To actually
/// dispatch the request, call [`dispatch`] on the returned request.
///
/// [`dispatch`]: /rocket/local/struct.LocalRequest.html#method.dispatch
/// dispatch the request, call [`LocalRequest::dispatch()`] on the returned
/// request.
///
/// # Example
///
@ -173,9 +170,8 @@ impl Client {
///
/// When dispatched, the request will be served by the instance of Rocket
/// within `self`. The request is not dispatched automatically. To actually
/// dispatch the request, call [`dispatch`] on the returned request.
///
/// [`dispatch`]: /rocket/local/struct.LocalRequest.html#method.dispatch
/// dispatch the request, call [`LocalRequest::dispatch()`] on the returned
/// request.
///
/// # Example
///
@ -194,9 +190,8 @@ impl Client {
///
/// When dispatched, the request will be served by the instance of Rocket
/// within `self`. The request is not dispatched automatically. To actually
/// dispatch the request, call [`dispatch`] on the returned request.
///
/// [`dispatch`]: /rocket/local/struct.LocalRequest.html#method.dispatch
/// dispatch the request, call [`LocalRequest::dispatch()`] on the returned
/// request.
///
/// # Example
///
@ -219,9 +214,8 @@ impl Client {
///
/// When dispatched, the request will be served by the instance of Rocket
/// within `self`. The request is not dispatched automatically. To actually
/// dispatch the request, call [`dispatch`] on the returned request.
///
/// [`dispatch`]: /rocket/local/struct.LocalRequest.html#method.dispatch
/// dispatch the request, call [`LocalRequest::dispatch()`] on the returned
/// request.
///
/// # Example
///
@ -242,9 +236,8 @@ impl Client {
///
/// When dispatched, the request will be served by the instance of Rocket
/// within `self`. The request is not dispatched automatically. To actually
/// dispatch the request, call [`dispatch`] on the returned request.
///
/// [`dispatch`]: /rocket/local/struct.LocalRequest.html#method.dispatch
/// dispatch the request, call [`LocalRequest::dispatch()`] on the returned
/// request.
///
/// # Example
///
@ -265,9 +258,8 @@ impl Client {
///
/// When dispatched, the request will be served by the instance of Rocket
/// within `self`. The request is not dispatched automatically. To actually
/// dispatch the request, call [`dispatch`] on the returned request.
///
/// [`dispatch`]: /rocket/local/struct.LocalRequest.html#method.dispatch
/// dispatch the request, call [`LocalRequest::dispatch()`] on the returned
/// request.
///
/// # Example
///
@ -288,9 +280,8 @@ impl Client {
///
/// When dispatched, the request will be served by the instance of Rocket
/// within `self`. The request is not dispatched automatically. To actually
/// dispatch the request, call [`dispatch`] on the returned request.
///
/// [`dispatch`]: /rocket/local/struct.LocalRequest.html#method.dispatch
/// dispatch the request, call [`LocalRequest::dispatch()`] on the returned
/// request.
///
/// # Example
///
@ -311,9 +302,8 @@ impl Client {
///
/// When dispatched, the request will be served by the instance of Rocket
/// within `self`. The request is not dispatched automatically. To actually
/// dispatch the request, call [`dispatch`] on the returned request.
///
/// [`dispatch`]: /rocket/local/struct.LocalRequest.html#method.dispatch
/// dispatch the request, call [`LocalRequest::dispatch()`] on the returned
/// request.
///
/// # Example
///

6
core/lib/src/local/mod.rs
View File

@ -95,10 +95,8 @@
//! }
//! ```
//!
//! [`Client`]: /rocket/local/struct.Client.html
//! [`LocalRequest`]: /rocket/local/struct.LocalRequest.html
//! [`Rocket`]: /rocket/struct.Rocket.html
//!
//! [`Client`]: local::Client
//! [`LocalRequest`]: local::LocalRequest
mod request;
mod client;

18
core/lib/src/local/request.rs
View File

@ -56,7 +56,7 @@ use local::Client;
/// same request needs to be dispatched multiple times, the request can first be
/// cloned and then dispatched: `request.clone().dispatch()`.
///
/// [`Client`]: /rocket/local/struct.Client.html
/// [`Client`]: ::local::Client
/// [`header`]: #method.header
/// [`add_header`]: #method.add_header
/// [`cookie`]: #method.cookie
@ -159,8 +159,8 @@ impl<'c> LocalRequest<'c> {
/// Any type that implements `Into<Header>` can be used here. Among others,
/// this includes [`ContentType`] and [`Accept`].
///
/// [`ContentType`]: /rocket/http/struct.ContentType.html
/// [`Accept`]: /rocket/http/struct.Accept.html
/// [`ContentType`]: ::http::ContentType
/// [`Accept`]: ::http::Accept
///
/// # Examples
///
@ -266,7 +266,7 @@ impl<'c> LocalRequest<'c> {
/// Add a [private cookie] to this request.
///
/// [private cookie]: /rocket/http/enum.Cookies.html#private-cookies
/// [private cookie]: ::http::Cookies::add_private()
///
/// # Examples
///
@ -438,12 +438,10 @@ impl<'c> fmt::Debug for LocalRequest<'c> {
/// A structure representing a response from dispatching a local request.
///
/// This structure is a thin wrapper around [`Response`]. It implements no
/// methods of its own; all functionality is exposed via the `Deref` and
/// `DerefMut` implementations with a target of `Response`. In other words, when
/// invoking methods, a `LocalResponse` can be treated exactly as if it were a
/// `Response`.
///
/// [`Response`]: /rocket/struct.Response.html
/// methods of its own; all functionality is exposed via the [`Deref`] and
/// [`DerefMut`] implementations with a target of `Response`. In other words,
/// when invoking methods, a `LocalResponse` can be treated exactly as if it
/// were a `Response`.
pub struct LocalResponse<'c> {
_request: Rc<Request<'c>>,
response: Response<'c>,

11
core/lib/src/outcome.rs
View File

@ -9,11 +9,9 @@
//! processing next.
//!
//! The `Outcome` type is the return type of many of the core Rocket traits,
//! including [FromRequest](/rocket/request/trait.FromRequest.html),
//! [FromData](/rocket/data/trait.FromData.html), and
//! [Responder](/rocket/response/trait.Responder.html). It is also the return
//! type of request handlers via the
//! [Response](/rocket/response/struct.Response.html) type.
//! including [`FromRequest`](::request::FromRequest),
//! [`FromData`](::data::FromData), and [`Responder`](::response::Responder). It
//! is also the return type of request handlers via the [`Response`] type.
//!
//! # Success
//!
@ -89,8 +87,7 @@ use self::Outcome::*;
/// An enum representing success (`Success`), failure (`Failure`), or
/// forwarding (`Forward`).
///
/// See the [top level documentation](/rocket/outcome/) for detailed
/// information.
/// See the [top level documentation](::outcome) for detailed information.
#[must_use]
#[derive(Clone, Copy, PartialEq, PartialOrd, Eq, Ord, Hash)]
pub enum Outcome<S, E, F> {

7
core/lib/src/request/form/error.rs
View File

@ -1,7 +1,8 @@
use std::io;
use http::RawStr;
/// Error returned by the [`FromForm`] derive on form parsing errors.
/// Error returned by the [`FromForm`](::request::FromForm) derive on form
/// parsing errors.
///
/// If multiple errors occur while parsing a form, the first error in the
/// following precedence, from highest to lowest, is returned:
@ -21,8 +22,8 @@ pub enum FormParseError<'f> {
Missing(&'f RawStr),
}
/// Error returned by the [`FromData`] implementations of [`Form`] and
/// [`LenientForm`].
/// Error returned by the [`FromData`](::data::FromData) implementations of
/// [`Form`](::request::Form) and [`LenientForm`](::request::LenientForm).
#[derive(Debug)]
pub enum FormDataError<'f, E> {
Io(io::Error),

10
core/lib/src/request/form/form.rs
View File

@ -7,7 +7,7 @@ use http::{Status, uri::FromUriParam};
/// A data guard for parsing [`FromForm`] types strictly.
///
/// This type implements the [`FromData]` trait. It provides a generic means to
/// This type implements the [`FromData`] trait. It provides a generic means to
/// parse arbitrary structures from incoming form data.
///
/// # Strictness
@ -17,7 +17,7 @@ use http::{Status, uri::FromUriParam};
/// error on missing and/or extra fields. For instance, if an incoming form
/// contains the fields "a", "b", and "c" while `T` only contains "a" and "c",
/// the form _will not_ parse as `Form<T>`. If you would like to admit extra
/// fields without error, see [`LenientForm`].
/// fields without error, see [`LenientForm`](::request::LenientForm).
///
/// # Usage
///
@ -96,9 +96,9 @@ use http::{Status, uri::FromUriParam};
/// depends on your use case. The primary question to answer is: _Can the input
/// contain characters that must be URL encoded?_ Note that this includes
/// common characters such as spaces. If so, then you must use `String`, whose
/// [`FromFormValue`] implementation automatically URL decodes strings. Because
/// the `&RawStr` references will refer directly to the underlying form data,
/// they will be raw and URL encoded.
/// [`FromFormValue`](::request::FromFormValue) implementation automatically URL
/// decodes strings. Because the `&RawStr` references will refer directly to the
/// underlying form data, they will be raw and URL encoded.
///
/// If your string values will not contain URL encoded characters, using
/// `&RawStr` will result in fewer allocation and is thus preferred.

16
core/lib/src/request/form/form_items.rs
View File

@ -41,17 +41,17 @@ use http::RawStr;
/// associated key/value pairs of the form item, either directly access them via
/// the [`key`](FormItem.key) and [`value`](FormItem.value) fields, use the
/// [`FormItem::key_value()`] method to get a tuple of the _raw_ `(key, value)`,
/// or use the [`FormItems::key_value_decoded()`] method to get a tuple of the
/// decoded (`key`, `value`).
/// or use the [`key_value_decoded()`](FormItem::key_value_decoded()) method to
/// get a tuple of the decoded (`key`, `value`).
///
/// # Completion
///
/// The iterator keeps track of whether the form string was parsed to completion
/// to determine if the form string was malformed. The iterator can be queried
/// for completion via the [completed](#method.completed) method, which returns
/// `true` if the iterator parsed the entire string that was passed to it. The
/// iterator can also attempt to parse any remaining contents via
/// [exhaust](#method.exhaust); this method returns `true` if exhaustion
/// for completion via the [`completed()`](#method.completed) method, which
/// returns `true` if the iterator parsed the entire string that was passed to
/// it. The iterator can also attempt to parse any remaining contents via
/// [`exhaust()`](#method.exhaust); this method returns `true` if exhaustion
/// succeeded.
///
/// This iterator guarantees that all valid form strings are parsed to
@ -123,13 +123,13 @@ pub struct FormItem<'f> {
///
/// **Note:** The key is _not_ URL decoded. To URL decode the raw strings,
/// use the [`RawStr::url_decode()`] method or access key-value pairs with
/// [`FromItem::key_value_decoded()`].
/// [`key_value_decoded()`](FormItem::key_value_decoded()).
pub key: &'f RawStr,
/// The value for the item, which may be empty if `key` is nonempty.
///
/// **Note:** The value is _not_ URL decoded. To URL decode the raw strings,
/// use the [`RawStr::url_decode()`] method or access key-value pairs with
/// [`FromItem::key_value_decoded()`].
/// [`key_value_decoded()`](FormItem::key_value_decoded()).
pub value: &'f RawStr
}

27
core/lib/src/request/form/from_form.rs
View File

@ -1,22 +1,21 @@
use request::FormItems;
/// Trait to create an instance of some type from an HTTP form.
/// [Form](struct.Form.html) requires its generic type to implement this trait.
/// [`Form`](::request::Form) requires its generic type to implement this trait.
///
/// # Deriving
///
/// This trait can be automatically derived. When deriving `FromForm`, every
/// field in the structure must implement [`FromFormValue`]. Rocket validates
/// each field in the structure by calling its `FromFormValue` implementation.
/// You may wish to implement `FromFormValue` for your own types for custom,
/// automatic validation.
/// field in the structure must implement
/// [`FromFormValue`](::request::FromFormValue). Rocket validates each field in
/// the structure by calling its `FromFormValue` implementation. You may wish to
/// implement `FromFormValue` for your own types for custom, automatic
/// validation.
///
/// ```rust
/// #![feature(proc_macro_hygiene, decl_macro)]
/// # #![feature(proc_macro_hygiene, decl_macro)]
/// # #![allow(deprecated, dead_code, unused_attributes)]
///
/// #[macro_use] extern crate rocket;
///
/// # #[macro_use] extern crate rocket;
/// #[derive(FromForm)]
/// struct TodoTask {
/// description: String,
@ -49,11 +48,11 @@ use request::FormItems;
/// Implementing `FromForm` should be a rare occurrence. Prefer instead to use
/// Rocket's built-in derivation.
///
/// When implementing `FromForm`, use the [FormItems](struct.FormItems.html)
/// iterator to iterate through the raw form key/value pairs. Be aware that form
/// fields that are typically hidden from your application, such as `_method`,
/// will be present while iterating. Ensure that you adhere to the properties of
/// the `strict` parameter, as detailed in the documentation below.
/// When implementing `FromForm`, use the [`FormItems`] iterator to iterate
/// through the raw form key/value pairs. Be aware that form fields that are
/// typically hidden from your application, such as `_method`, will be present
/// while iterating. Ensure that you adhere to the properties of the `strict`
/// parameter, as detailed in the documentation below.
///
/// ## Example
///

4
core/lib/src/request/form/from_form_value.rs
View File

@ -4,7 +4,7 @@ use std::str::FromStr;
use http::RawStr;
/// Trait to create instance of some type from a form value; expected from field
/// types in structs deriving `FromForm`.
/// types in structs deriving [`FromForm`](::request::FromForm).
///
/// When deriving the `FromForm` trait, Rocket uses the `FromFormValue`
/// implementation of each field's type to validate the form input. To
@ -67,7 +67,7 @@ use http::RawStr;
/// `"false"`, `"off"`, or not present. In any other case, the raw form
/// value is returned in the `Err` value.
///
/// * **&[RawStr](/rocket/http/struct.RawStr.html)**
/// * **[`&RawStr`](RawStr)**
///
/// _This implementation always returns successfully._
///

47
core/lib/src/request/from_request.rs
View File

@ -66,26 +66,26 @@ impl<S, E> IntoOutcome<S, (Status, E), ()> for Result<S, E> {
///
/// # Outcomes
///
/// The returned [Outcome](/rocket/outcome/index.html) of a `from_request` call
/// determines how the incoming request will be processed.
/// The returned [`Outcome`] of a `from_request` call determines how the
/// incoming request will be processed.
///
/// * **Success**(S)
///
/// If the `Outcome` is `Success`, then the `Success` value will be used as
/// If the `Outcome` is [`Success`], then the `Success` value will be used as
/// the value for the corresponding parameter. As long as all other guards
/// succeed, the request will be handled.
///
/// * **Failure**(Status, E)
///
/// If the `Outcome` is `Failure`, the request will fail with the given status
/// code and error. The designated error
/// [Catcher](/rocket/struct.Catcher.html) will be used to respond to the
/// request. Note that users can request types of `Result<S, E>` and
/// `Option<S>` to catch `Failure`s and retrieve the error value.
/// If the `Outcome` is [`Failure`], the request will fail with the given
/// status code and error. The designated error [`Catcher`](::Catcher) will be
/// used to respond to the request. Note that users can request types of
/// `Result<S, E>` and `Option<S>` to catch `Failure`s and retrieve the error
/// value.
///
/// * **Forward**
///
/// If the `Outcome` is `Forward`, the request will be forwarded to the next
/// If the `Outcome` is [`Forward`], the request will be forwarded to the next
/// matching request. Note that users can request an `Option<S>` to catch
/// `Forward`s.
///
@ -96,45 +96,40 @@ impl<S, E> IntoOutcome<S, (Status, E), ()> for Result<S, E> {
///
/// * **Method**
///
/// Extracts the [Method](/rocket/http/enum.Method.html) from the incoming
/// request.
/// Extracts the [`Method`] from the incoming request.
///
/// _This implementation always returns successfully._
///
/// * **&Origin**
///
/// Extracts the [`Origin`](/rocket/http/uri/struct.Origin.html) URI from
/// the incoming request.
/// Extracts the [`Origin`] URI from the incoming request.
///
/// _This implementation always returns successfully._
///
/// * **&Route**
///
/// Extracts the [Route](/rocket/struct.Route.html) from the request if one
/// is available. If a route is not available, the request is forwarded.
/// Extracts the [`Route`] from the request if one is available. If a route
/// is not available, the request is forwarded.
///
/// For information on when an `&Route` is available, see the
/// [`Request::route`](/rocket/struct.Request.html#method.route)
/// documentation.
/// For information on when an `&Route` is available, see
/// [`Request::route()`].
///
/// * **Cookies**
///
/// Returns a borrow to the [Cookies](/rocket/http/enum.Cookies.html) in
/// the incoming request. Note that `Cookies` implements internal
/// mutability, so a handle to `Cookies` allows you to get _and_ set cookies
/// in the request.
/// Returns a borrow to the [`Cookies`] in the incoming request. Note that
/// `Cookies` implements internal mutability, so a handle to `Cookies`
/// allows you to get _and_ set cookies in the request.
///
/// _This implementation always returns successfully._
///
/// * **ContentType**
///
/// Extracts the [ContentType](/rocket/http/struct.ContentType.html) from
/// the incoming request. If the request didn't specify a Content-Type, the
/// request is forwarded.
/// Extracts the [`ContentType`] from the incoming request. If the request
/// didn't specify a Content-Type, the request is forwarded.
///
/// * **SocketAddr**
///
/// Extracts the remote address of the incoming request as a `SocketAddr`.
/// Extracts the remote address of the incoming request as a [`SocketAddr`].
/// If the remote address is not known, the request is forwarded.
///
/// _This implementation always returns successfully._

16
core/lib/src/request/param.rs
View File

@ -79,7 +79,7 @@ use http::{RawStr, uri::{Segments, SegmentError}};
/// type returns successfully. Otherwise, the raw path segment is returned
/// in the `Err` value.
///
/// * **&[`RawStr`](/rocket/http/struct.RawStr.html)**
/// * **[`&RawStr`](RawStr)**
///
/// _This implementation always returns successfully._
///
@ -116,7 +116,7 @@ use http::{RawStr, uri::{Segments, SegmentError}};
///
/// Say you want to parse a segment of the form:
///
/// ```ignore
/// ```text
/// [a-zA-Z]+:[0-9]+
/// ```
///
@ -271,13 +271,11 @@ impl<'a, T: FromParam<'a>> FromParam<'a> for Option<T> {
/// Trait to convert _many_ dynamic path segment strings to a concrete value.
///
/// This is the `..` analog to [FromParam](trait.FromParam.html), and its
/// functionality is identical to it with one exception: this trait applies to
/// segment parameters of the form `<param..>`, where `param` is of some type
/// `T` that implements `FromSegments`. `T::from_segments` is called to convert
/// the matched segments (via the
/// [Segments](/rocket/http/uri/struct.Segments.html) iterator) into the
/// implementing type.
/// This is the `..` analog to [`FromParam`], and its functionality is identical
/// to it with one exception: this trait applies to segment parameters of the
/// form `<param..>`, where `param` is of some type `T` that implements
/// `FromSegments`. `T::from_segments` is called to convert the matched segments
/// (via the [`Segments`] iterator) into the implementing type.
///
/// # Provided Implementations
///

43
core/lib/src/request/request.rs
View File

@ -23,8 +23,7 @@ type Indices = (usize, usize);
/// The type of an incoming web request.
///
/// This should be used sparingly in Rocket applications. In particular, it
/// should likely only be used when writing
/// [FromRequest](/rocket/request/trait.FromRequest.html) implementations. It
/// should likely only be used when writing [`FromRequest`] implementations. It
/// contains all of the information for a given web request except for the body
/// data. This includes the HTTP method, URI, cookies, headers, and more.
#[derive(Clone)]
@ -124,7 +123,7 @@ impl<'r> Request<'r> {
self._set_method(method);
}
/// Borrow the `Origin` URI from `self`.
/// Borrow the [`Origin`] URI from `self`.
///
/// # Example
///
@ -271,9 +270,8 @@ impl<'r> Request<'r> {
/// Returns a wrapped borrow to the cookies in `self`.
///
/// [`Cookies`](/rocket/http/enum.Cookies.html) implements internal
/// mutability, so this method allows you to get _and_ add/remove cookies in
/// `self`.
/// [`Cookies`] implements internal mutability, so this method allows you to
/// get _and_ add/remove cookies in `self`.
///
/// # Example
///
@ -303,8 +301,7 @@ impl<'r> Request<'r> {
}
}
/// Returns a [`HeaderMap`](/rocket/http/struct.HeaderMap.html) of all of
/// the headers in `self`.
/// Returns a [`HeaderMap`] of all of the headers in `self`.
///
/// # Example
///
@ -323,8 +320,7 @@ impl<'r> Request<'r> {
/// Add `header` to `self`'s headers. The type of `header` can be any type
/// that implements the `Into<Header>` trait. This includes common types
/// such as [`ContentType`](/rocket/http/struct.ContentType.html) and
/// [`Accept`](/rocket/http/struct.Accept.html).
/// such as [`ContentType`] and [`Accept`].
///
/// # Example
///
@ -509,16 +505,26 @@ impl<'r> Request<'r> {
///
/// Assuming a `User` request guard exists, invoke it:
///
/// ```rust,ignore
/// ```rust
/// # use rocket::Request;
/// # use rocket::http::Method;
/// # type User = Method;
/// # Request::example(Method::Get, "/uri", |request| {
/// let outcome = request.guard::<User>();
/// # });
/// ```
///
/// Retrieve managed state inside of a guard implementation:
///
/// ```rust,ignore
/// ```rust
/// # use rocket::Request;
/// # use rocket::http::Method;
/// use rocket::State;
///
/// let pool = request.guard::<State<Pool>>()?;
/// # type Pool = usize;
/// # Request::example(Method::Get, "/uri", |request| {
/// let pool = request.guard::<State<Pool>>();
/// # });
/// ```
#[inline(always)]
pub fn guard<'a, T: FromRequest<'a, 'r>>(&'a self) -> Outcome<T, T::Error> {
@ -535,10 +541,9 @@ impl<'r> Request<'r> {
/// ```rust
/// # use rocket::http::Method;
/// # use rocket::Request;
/// # struct User;
/// # type User = ();
/// fn current_user(request: &Request) -> User {
/// // Validate request for a given user, load from database, etc.
/// # User
/// }
///
/// # Request::example(Method::Get, "/uri", |request| {
@ -596,8 +601,7 @@ impl<'r> Request<'r> {
/// Retrieves and parses into `T` all of the path segments in the request
/// URI beginning and including the 0-indexed `n`th non-empty segment. `T`
/// must implement [FromSegments](/rocket/request/trait.FromSegments.html),
/// which is used to parse the segments.
/// must implement [`FromSegments`], which is used to parse the segments.
///
/// This method exists only to be used by manual routing. To retrieve
/// segments from a request, use Rocket's code generation facilities.
@ -676,11 +680,6 @@ impl<'r> Request<'r> {
/// assert_eq!(value(req, "/?a=apple&z=zebra", "apple").as_str(), "n/a");
/// # });
/// ```
/// # Example
///
/// If the request query is `"/?apple=value_for_a&z=zebra"`, then
/// `request.get_query_value::<T>("z")` will attempt to parse `"zebra"` as
/// type `T`.
#[inline]
pub fn get_query_value<'a, T>(&'a self, key: &str) -> Option<Result<T, T::Error>>
where T: FromFormValue<'a>

21
core/lib/src/request/state.rs
View File

@ -9,10 +9,10 @@ use http::Status;
/// This type can be used as a request guard to retrieve the state Rocket is
/// managing for some type `T`. This allows for the sharing of state across any
/// number of handlers. A value for the given type must previously have been
/// registered to be managed by Rocket via the
/// [manage](/rocket/struct.Rocket.html#method.manage) method. The type being
/// managed must be thread safe and sendable across thread boundaries. In other
/// words, it must implement `Send + Sync + 'static`.
/// registered to be managed by Rocket via
/// [`Rocket::manage()`](::Rocket::manage()). The type being managed must be
/// thread safe and sendable across thread boundaries. In other words, it must
/// implement [`Send`] + [`Sync`] + 'static`.
///
/// # Example
///
@ -59,11 +59,9 @@ use http::Status;
///
/// Because `State` is itself a request guard, managed state can be retrieved
/// from another request guard's implementation. In the following code example,
/// `Item` retrieves the `MyConfig` managed state in its `FromRequest`
/// `Item` retrieves the `MyConfig` managed state in its [`FromRequest`]
/// implementation using the [`Request::guard()`] method.
///
/// [`Request::guard()`]: /rocket/struct.Request.html#method.guard
///
/// ```rust
/// use rocket::State;
/// use rocket::request::{self, Request, FromRequest};
@ -86,10 +84,10 @@ pub struct State<'r, T: Send + Sync + 'static>(&'r T);
impl<'r, T: Send + Sync + 'static> State<'r, T> {
/// Retrieve a borrow to the underlying value with a lifetime of `'r`.
///
/// Using this method is typically unnecessary as `State` implements `Deref`
/// with a `Target` of `T`. This means Rocket will automatically coerce a
/// `State<T>` to an `&T` as required. This method should only be used when
/// a longer lifetime is required.
/// Using this method is typically unnecessary as `State` implements
/// [`Deref`] with a [`Deref::Target`] of `T`. This means Rocket will
/// automatically coerce a `State<T>` to an `&T` as required. This method
/// should only be used when a longer lifetime is required.
///
/// # Example
///
@ -116,7 +114,6 @@ impl<'r, T: Send + Sync + 'static> State<'r, T> {
}
}
// TODO: Doc.
impl<'a, 'r, T: Send + Sync + 'static> FromRequest<'a, 'r> for State<'r, T> {
type Error = ();

15
core/lib/src/response/flash.rs
View File

@ -12,8 +12,7 @@ use std::sync::atomic::{AtomicBool, Ordering};
const FLASH_COOKIE_NAME: &str = "_flash";
/// Sets a "flash" cookie that will be removed when it is accessed. The
/// analogous request type is
/// [FlashMessage](/rocket/request/type.FlashMessage.html).
/// analogous request type is [`FlashMessage`].
///
/// This type makes it easy to send messages across requests. It is typically
/// used for "status" messages after redirects. For instance, if a user attempts
@ -30,9 +29,8 @@ const FLASH_COOKIE_NAME: &str = "_flash";
/// [error](#method.error) constructors create messages with the corresponding
/// names.
///
/// Messages can be retrieved on the request side via the
/// [FlashMessage](/rocket/request/type.FlashMessage.html) type and the
/// [name](#method.name) and [msg](#method.msg) methods.
/// Messages can be retrieved on the request side via the [`FlashMessage`] type
/// and the [name](#method.name) and [msg](#method.msg) methods.
///
/// # Response
///
@ -89,8 +87,7 @@ pub struct Flash<R> {
inner: R,
}
/// Type alias to retrieve [`Flash`](/rocket/response/struct.Flash.html)
/// messages from a request.
/// Type alias to retrieve [`Flash`] messages from a request.
///
/// # Flash Cookie
///
@ -101,8 +98,8 @@ pub struct Flash<R> {
/// The flash cookie is cleared if either the [`name()`] or [`msg()`] method is
/// called. If neither method is called, the flash cookie is not cleared.
///
/// [`name()`]: /rocket/response.struct.Flash.html#method.name
/// [`msg()`]: /rocket/response.struct.Flash.html#method.msg
/// [`name()`]: Flash::name()
/// [`msg()`]: Flash::msg()
pub type FlashMessage<'a, 'r> = ::response::Flash<&'a Request<'r>>;
impl<'r, R: Responder<'r>> Flash<R> {

11
core/lib/src/response/mod.rs
View File

@ -1,8 +1,9 @@
//! Types and traits to build and send responses.
//!
//! The return type of a Rocket handler can be any type that implements the
//! [Responder](trait.Responder.html) trait. Among other things, this module
//! contains several such types.
//! [`Responder`](::response::Responder) trait, which means that the type knows
//! how to generate a [`Response`]. Among other things, this module contains
//! several such types.
//!
//! # Composing
//!
@ -15,9 +16,9 @@
//!
//! # Contrib
//!
//! The [`contrib` crate](/rocket_contrib) contains several useful `Responder`s
//! including [`Template`](/rocket_contrib/struct.Template.html) and
//! [`Json`](/rocket_contrib/struct.Json.html).
//! The [`contrib` crate](rocket_contrib) contains several useful `Responder`s
//! including [`Template`](rocket_contrib::Template) and
//! [`Json`](rocket_contrib::Json).
mod responder;
mod redirect;

9
core/lib/src/response/named_file.rs
View File

@ -19,7 +19,7 @@ impl NamedFile {
///
/// This function will return an error if path does not already exist. Other
/// errors may also be returned according to
/// [OpenOptions::open](https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.open).
/// [`OpenOptions::open()`](std::fs::OpenOptions::open()).
///
/// # Examples
///
@ -75,10 +75,9 @@ impl NamedFile {
/// Streams the named file to the client. Sets or overrides the Content-Type in
/// the response according to the file's extension if the extension is
/// recognized. See
/// [ContentType::from_extension](/rocket/http/struct.ContentType.html#method.from_extension)
/// for more information. If you would like to stream a file with a different
/// Content-Type than that implied by its extension, use a `File` directly.
/// recognized. See [`ContentType::from_extension()`] for more information. If
/// you would like to stream a file with a different Content-Type than that
/// implied by its extension, use a [`File`] directly.
impl<'r> Responder<'r> for NamedFile {
fn respond_to(self, req: &Request) -> response::Result<'r> {
let mut response = self.1.respond_to(req)?;

22
core/lib/src/response/responder.rs
View File

@ -9,14 +9,18 @@ use request::Request;
/// Trait implemented by types that generate responses for clients.
///
/// Types that implement this trait can be used as the return type of a handler,
/// as illustrated below:
/// as illustrated below with `T`:
///
/// ```rust,ignore
/// ```rust
/// # #![feature(proc_macro_hygiene, decl_macro)]
/// # #[macro_use] extern crate rocket;
/// # type T = ();
/// #
/// #[get("/")]
/// fn index() -> T { ... }
/// fn index() -> T { /* ... */ }
/// ```
///
/// In this example, `T` can be any type that implements `Responder`.
/// In this example, `T` can be any type, as long as it implements `Responder`.
///
/// # Return Value
///
@ -66,8 +70,7 @@ use request::Request;
///
/// Responds with a streamed body containing the data in the `File`. No
/// `Content-Type` is set. To automatically have a `Content-Type` set based
/// on the file's extension, use
/// [`NamedFile`](/rocket/response/struct.NamedFile.html).
/// on the file's extension, use [`NamedFile`](::response::NamedFile).
///
/// * **()**
///
@ -107,10 +110,9 @@ use request::Request;
/// ## Joining and Merging
///
/// When chaining/wrapping other `Responder`s, use the
/// [merge](/rocket/struct.Response.html#method.merge) or
/// [join](/rocket/struct.Response.html#method.join) methods on the `Response`
/// or `ResponseBuilder` struct. Ensure that you document the merging or joining
/// behavior appropriately.
/// [`merge()`](Response::merge()) or [`join()`](Response::join()) methods on
/// the `Response` or `ResponseBuilder` struct. Ensure that you document the
/// merging or joining behavior appropriately.
///
/// ## Inspecting Requests
///

47
core/lib/src/response/response.rs
View File

@ -98,19 +98,19 @@ impl<T> fmt::Debug for Body<T> {
/// Type for easily building `Response`s.
///
/// Building a [Response](struct.Response.html) can be a low-level ordeal; this
/// structure presents a higher-level API that simplifies building `Response`s.
/// Building a [`Response`] can be a low-level ordeal; this structure presents a
/// higher-level API that simplifies building `Response`s.
///
/// # Usage
///
/// `ResponseBuilder` follows the builder pattern and is usually obtained by
/// calling [build](struct.Response.html#method.build) on `Response`. Almost all
/// methods take the current builder as a mutable reference and return the same
/// mutable reference with field(s) modified in the `Responder` being built.
/// These method calls can be chained: `build.a().b()`.
/// calling [`Response::build()`] on `Response`. Almost all methods take the
/// current builder as a mutable reference and return the same mutable reference
/// with field(s) modified in the `Responder` being built. These method calls
/// can be chained: `build.a().b()`.
///
/// To finish building and retrieve the built `Response`, use the
/// [finalize](#method.finalize) or [ok](#method.ok) methods.
/// [`finalize()`](#method.finalize) or [`ok()`](#method.ok) methods.
///
/// ## Headers
///
@ -223,9 +223,8 @@ impl<'r> ResponseBuilder<'r> {
/// value will remain.
///
/// The type of `header` can be any type that implements `Into<Header>`.
/// This includes `Header` itself,
/// [ContentType](/rocket/http/struct.ContentType.html) and [hyper::header
/// types](/rocket/http/hyper/header/index.html).
/// This includes `Header` itself, [`ContentType`](::http::ContentType) and
/// [hyper::header types](::http::hyper::header).
///
/// # Example
///
@ -254,9 +253,8 @@ impl<'r> ResponseBuilder<'r> {
/// potentially different values to be present in the `Response`.
///
/// The type of `header` can be any type that implements `Into<Header>`.
/// This includes `Header` itself,
/// [ContentType](/rocket/http/struct.ContentType.html) and [hyper::header
/// types](/rocket/http/hyper/header/index.html).
/// This includes `Header` itself, [`ContentType`](::http::ContentType) and
/// [hyper::header types](::http::hyper::header).
///
/// # Example
///
@ -557,7 +555,7 @@ impl<'r> ResponseBuilder<'r> {
}
}
/// A response, as returned by `Responder`s.
/// A response, as returned by types implementing [`Responder`].
#[derive(Default)]
pub struct Response<'r> {
status: Option<Status>,
@ -720,8 +718,7 @@ impl<'r> Response<'r> {
cookies
}
/// Returns a [`HeaderMap`](/rocket/http/struct.HeaderMap.html) of all of
/// the headers in `self`.
/// Returns a [`HeaderMap`] of all of the headers in `self`.
///
/// # Example
///
@ -746,8 +743,8 @@ impl<'r> Response<'r> {
/// Sets the header `header` in `self`. Any existing headers with the name
/// `header.name` will be lost, and only `header` will remain. The type of
/// `header` can be any type that implements `Into<Header>`. This includes
/// `Header` itself, [`ContentType`](/rocket/http/struct.ContentType.html)
/// and [`hyper::header` types](/rocket/http/hyper/header/index.html).
/// `Header` itself, [`ContentType`](::http::ContentType) and
/// [`hyper::header` types](::http::hyper::header).
///
/// # Example
///
@ -802,8 +799,8 @@ impl<'r> Response<'r> {
/// name `header.name`, another header with the same name and value
/// `header.value` is added. The type of `header` can be any type that
/// implements `Into<Header>`. This includes `Header` itself,
/// [`ContentType`](/rocket/http/struct.ContentType.html) and
/// [`hyper::header` types](/rocket/http/hyper/header/index.html).
/// [`ContentType`](::http::ContentType) and [`hyper::header`
/// types](::http::hyper::header).
///
/// # Example
///
@ -828,9 +825,9 @@ impl<'r> Response<'r> {
/// Adds a custom header with name `name` and value `value` to `self`. If
/// `self` already contains headers with the name `name`, another header
/// with the same `name` and `value` is added. The type of `header` can be
/// any type that implements `Into<Header>`. This includes `Header` itself,
/// [`ContentType`](/rocket/http/struct.ContentType.html) and
/// [`hyper::header` types](/rocket/http/hyper/header/index.html).
/// any type implements `Into<Header>`. This includes `Header` itself,
/// [`ContentType`](::http::ContentType) and [`hyper::header`
/// types](::http::hyper::header).
///
/// # Example
///
@ -1018,8 +1015,8 @@ impl<'r> Response<'r> {
/// Sets the body of `self` to be `body`, which will be streamed. The chunk
/// size of the stream is
/// [DEFAULT_CHUNK_SIZE](/rocket/response/constant.DEFAULT_CHUNK_SIZE.html).
/// Use [set_chunked_body](#method.set_chunked_body) for custom chunk sizes.
/// [DEFAULT_CHUNK_SIZE](::response::DEFAULT_CHUNK_SIZE). Use
/// [set_chunked_body](#method.set_chunked_body) for custom chunk sizes.
///
/// # Example
///

17
core/lib/src/rocket.rs
View File

@ -330,11 +330,11 @@ impl Rocket {
/// Create a new `Rocket` application using the configuration information in
/// `Rocket.toml`. If the file does not exist or if there is an I/O error
/// reading the file, the defaults are used. See the
/// [config](/rocket/config/index.html) documentation for more information
/// on defaults.
/// reading the file, the defaults are used. See the [`config`]
/// documentation for more information on defaults.
///
/// This method is typically called through the `rocket::ignite` alias.
/// This method is typically called through the
/// [`rocket::ignite()`](::ignite) alias.
///
/// # Panics
///
@ -570,10 +570,9 @@ impl Rocket {
/// refers to a different `T`.
///
/// Managed state can be retrieved by any request handler via the
/// [State](/rocket/struct.State.html) request guard. In particular, if a
/// value of type `T` is managed by Rocket, adding `State<T>` to the list of
/// arguments in a request handler instructs Rocket to retrieve the managed
/// value.
/// [`State`](::State) request guard. In particular, if a value of type `T`
/// is managed by Rocket, adding `State<T>` to the list of arguments in a
/// request handler instructs Rocket to retrieve the managed value.
///
/// # Panics
///
@ -670,8 +669,6 @@ impl Rocket {
/// without first being inspected. See the [`LaunchError`] documentation for
/// more information.
///
/// [`LaunchError`]: /rocket/error/struct.LaunchError.html
///
/// # Example
///
/// ```rust

1
scripts/bump_version.sh
View File

@ -12,6 +12,7 @@ fi
today=$(date "+%b %d, %Y")
find . -name "lib.rs" | xargs sed -i.bak "s/${1}/${2}/g"
find . -name "*.toml" | xargs sed -i.bak "s/${1}/${2}/g"
find site/ -name "*.md" | xargs sed -i.bak "s/${1}/${2}/g"
sed -i.bak "s/^date.*/date = \"$today\"/" site/index.toml