From 28f2a33abdb7e1d6f462955e0bc08883e2eb68db Mon Sep 17 00:00:00 2001 From: Sergio Benitez Date: Sat, 6 Oct 2018 06:25:17 -0700 Subject: [PATCH] Use inter/intra-crate links in all documentation. --- contrib/lib/src/databases.rs | 32 +++-- contrib/lib/src/json.rs | 32 ++--- contrib/lib/src/lib.rs | 18 ++- contrib/lib/src/templates/engine.rs | 9 +- contrib/lib/src/templates/metadata.rs | 8 +- contrib/lib/src/templates/mod.rs | 24 ++-- contrib/lib/src/uuid.rs | 4 +- core/codegen_next/src/lib.rs | 16 +-- core/http/src/accept.rs | 15 ++- core/http/src/cookies.rs | 28 ++--- core/http/src/header.rs | 5 +- core/http/src/lib.rs | 6 +- core/http/src/media_type.rs | 19 +-- core/http/src/raw_str.rs | 37 +++--- core/http/src/status.rs | 2 +- core/http/src/uri/from_uri_param.rs | 26 ++-- core/http/src/uri/origin.rs | 10 +- core/http/src/uri/uri.rs | 20 ++- core/http/src/uri/uri_display.rs | 15 +-- core/lib/src/catcher.rs | 7 +- core/lib/src/config/builder.rs | 3 +- core/lib/src/config/config.rs | 20 ++- core/lib/src/config/custom_values.rs | 3 +- core/lib/src/config/mod.rs | 38 +++--- core/lib/src/data/data.rs | 6 +- core/lib/src/data/data_stream.rs | 6 +- core/lib/src/data/from_data.rs | 22 ++-- core/lib/src/error.rs | 5 +- core/lib/src/fairing/info_kind.rs | 10 +- core/lib/src/fairing/mod.rs | 125 +++++++++---------- core/lib/src/lib.rs | 65 +++++----- core/lib/src/local/client.rs | 44 +++---- core/lib/src/local/mod.rs | 6 +- core/lib/src/local/request.rs | 18 ++- core/lib/src/outcome.rs | 11 +- core/lib/src/request/form/error.rs | 7 +- core/lib/src/request/form/form.rs | 10 +- core/lib/src/request/form/form_items.rs | 16 +-- core/lib/src/request/form/from_form.rs | 27 ++-- core/lib/src/request/form/from_form_value.rs | 4 +- core/lib/src/request/from_request.rs | 47 ++++--- core/lib/src/request/param.rs | 16 ++- core/lib/src/request/request.rs | 43 ++++--- core/lib/src/request/state.rs | 21 ++-- core/lib/src/response/flash.rs | 15 +-- core/lib/src/response/mod.rs | 11 +- core/lib/src/response/named_file.rs | 9 +- core/lib/src/response/responder.rs | 22 ++-- core/lib/src/response/response.rs | 47 ++++--- core/lib/src/rocket.rs | 17 ++- scripts/bump_version.sh | 1 + 51 files changed, 484 insertions(+), 544 deletions(-) diff --git a/contrib/lib/src/databases.rs b/contrib/lib/src/databases.rs index cb08e519..09465300 100644 --- a/contrib/lib/src/databases.rs +++ b/contrib/lib/src/databases.rs @@ -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 = ::std::result::Result; /// # +/// # impl ConnectionManager { +/// # pub fn new(url: &str) -> Result { 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; /// /// fn pool(config: DatabaseConfig) -> Result, 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)) /// } /// } /// ``` diff --git a/contrib/lib/src/json.rs b/contrib/lib/src/json.rs index f220695c..1d857689 100644 --- a/contrib/lib/src/json.rs +++ b/contrib/lib/src/json.rs @@ -164,8 +164,8 @@ impl DerefMut for Json { /// 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 DerefMut for Json { /// /// # 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")] diff --git a/contrib/lib/src/lib.rs b/contrib/lib/src/lib.rs index 322edab1..0586b15e 100644 --- a/contrib/lib/src/lib.rs +++ b/contrib/lib/src/lib.rs @@ -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 diff --git a/contrib/lib/src/templates/engine.rs b/contrib/lib/src/templates/engine.rs index b0c9c96e..c478df61 100644 --- a/contrib/lib/src/templates/engine.rs +++ b/contrib/lib/src/templates/engine.rs @@ -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, } diff --git a/contrib/lib/src/templates/metadata.rs b/contrib/lib/src/templates/metadata.rs index ecf6f4fa..35dfc779 100644 --- a/contrib/lib/src/templates/metadata.rs +++ b/contrib/lib/src/templates/metadata.rs @@ -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; diff --git a/contrib/lib/src/templates/mod.rs b/contrib/lib/src/templates/mod.rs index be8489bb..3616dd9e 100644 --- a/contrib/lib/src/templates/mod.rs +++ b/contrib/lib/src/templates/mod.rs @@ -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 diff --git a/contrib/lib/src/uuid.rs b/contrib/lib/src/uuid.rs index 72915276..a67849d5 100644 --- a/contrib/lib/src/uuid.rs +++ b/contrib/lib/src/uuid.rs @@ -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 /// diff --git a/core/codegen_next/src/lib.rs b/core/codegen_next/src/lib.rs index 27e8b9aa..2089f0fc 100644 --- a/core/codegen_next/src/lib.rs +++ b/core/codegen_next/src/lib.rs @@ -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 //! diff --git a/core/http/src/accept.rs b/core/http/src/accept.rs index b2a284a1..07fc9a74 100644 --- a/core/http/src/accept.rs +++ b/core/http/src/accept.rs @@ -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. diff --git a/core/http/src/cookies.rs b/core/http/src/cookies.rs index 32e6e552..80512e31 100644 --- a/core/http/src/cookies.rs +++ b/core/http/src/cookies.rs @@ -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 /// diff --git a/core/http/src/header.rs b/core/http/src/header.rs index d2a5e03e..dd52da63 100644 --- a/core/http/src/header.rs +++ b/core/http/src/header.rs @@ -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
` - /// 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 /// diff --git a/core/http/src/lib.rs b/core/http/src/lib.rs index 7fa68cd7..f3261666 100644 --- a/core/http/src/lib.rs +++ b/core/http/src/lib.rs @@ -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 #17), 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; diff --git a/core/http/src/media_type.rs b/core/http/src/media_type.rs index f57c6f70..7b324ccf 100644 --- a/core/http/src/media_type.rs +++ b/core/http/src/media_type.rs @@ -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. diff --git a/core/http/src/raw_str.rs b/core/http/src/raw_str.rs index 86ef8b7f..ebda863f 100644 --- a/core/http/src/raw_str.rs +++ b/core/http/src/raw_str.rs @@ -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); diff --git a/core/http/src/status.rs b/core/http/src/status.rs index bfcec3be..b1a19862 100644 --- a/core/http/src/status.rs +++ b/core/http/src/status.rs @@ -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 "] + #[doc="[`Status`] with code "] #[doc=$code_str] #[doc=" and reason "] #[doc=$reason] diff --git a/core/http/src/uri/from_uri_param.rs b/core/http/src/uri/from_uri_param.rs index 739360cb..5bd9fc86 100644 --- a/core/http/src/uri/from_uri_param.rs +++ b/core/http/src/uri/from_uri_param.rs @@ -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 { /// 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; } diff --git a/core/http/src/uri/origin.rs b/core/http/src/uri/origin.rs index 791a696f..51254d15 100644 --- a/core/http/src/uri/origin.rs +++ b/core/http/src/uri/origin.rs @@ -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 /// diff --git a/core/http/src/uri/uri.rs b/core/http/src/uri/uri.rs index 2e480f7c..6bcf5852 100644 --- a/core/http/src/uri/uri.rs +++ b/core/http/src/uri/uri.rs @@ -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` (for instance, in [`Redirect`](rocket::response::Redirect) +/// TryInto` (for instance, in [`Redirect`](::rocket::response::Redirect) /// methods). This means that you can provide any type `T` that implements /// `TryInto`, or, equivalently, any type `U` for which `Uri` implements /// `TryFrom` or `From`. 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, diff --git a/core/http/src/uri/uri_display.rs b/core/http/src/uri/uri_display.rs index 0cdac615..ae1cd63f 100644 --- a/core/http/src/uri/uri_display.rs +++ b/core/http/src/uri/uri_display.rs @@ -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`** /// /// 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 /// diff --git a/core/lib/src/catcher.rs b/core/lib/src/catcher.rs index e2bd0b66..eb6c532c 100644 --- a/core/lib/src/catcher.rs +++ b/core/lib/src/catcher.rs @@ -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, diff --git a/core/lib/src/config/builder.rs b/core/lib/src/config/builder.rs index 9a8a6b4f..d9acc4d9 100644 --- a/core/lib/src/config/builder.rs +++ b/core/lib/src/config/builder.rs @@ -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 /// diff --git a/core/lib/src/config/config.rs b/core/lib/src/config/config.rs index 13d254d2..fbcbf051 100644 --- a/core/lib/src/config/config.rs +++ b/core/lib/src/config/config.rs @@ -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 /// diff --git a/core/lib/src/config/custom_values.rs b/core/lib/src/config/custom_values.rs index 5b44e170..067228a0 100644 --- a/core/lib/src/config/custom_values.rs +++ b/core/lib/src/config/custom_values.rs @@ -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 /// diff --git a/core/lib/src/config/mod.rs b/core/lib/src/config/mod.rs index 9f289ac6..4532949a 100644 --- a/core/lib/src/config/mod.rs +++ b/core/lib/src/config/mod.rs @@ -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 = ::std::result::Result; #[doc(hidden)] diff --git a/core/lib/src/data/data.rs b/core/lib/src/data/data.rs index a9c7075c..c7dc1ed0 100644 --- a/core/lib/src/data/data.rs +++ b/core/lib/src/data/data.rs @@ -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 = ""` -/// route parameter as follows: +/// [`FromData`](::data::Data) are used via code generation by specifying the +/// `data = ""` 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 diff --git a/core/lib/src/data/data_stream.rs b/core/lib/src/data/data_stream.rs index 1aa20430..719e4b3a 100644 --- a/core/lib/src/data/data_stream.rs +++ b/core/lib/src/data/data_stream.rs @@ -11,9 +11,9 @@ pub type InnerStream = Chain>, 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 diff --git a/core/lib/src/data/from_data.rs b/core/lib/src/data/from_data.rs index b94481da..c007be1e 100644 --- a/core/lib/src/data/from_data.rs +++ b/core/lib/src/data/from_data.rs @@ -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` and -/// `Option` 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` and `Option` 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` 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._ /// diff --git a/core/lib/src/error.rs b/core/lib/src/error.rs index ce6d3afa..5cc9781f 100644 --- a/core/lib/src/error.rs +++ b/core/lib/src/error.rs @@ -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 /// diff --git a/core/lib/src/fairing/info_kind.rs b/core/lib/src/fairing/info_kind.rs index a950ce8b..a2a91f06 100644 --- a/core/lib/src/fairing/info_kind.rs +++ b/core/lib/src/fairing/info_kind.rs @@ -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: diff --git a/core/lib/src/fairing/mod.rs b/core/lib/src/fairing/mod.rs index ba337cd0..eb040286 100644 --- a/core/lib/src/fairing/mod.rs +++ b/core/lib/src/fairing/mod.rs @@ -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. diff --git a/core/lib/src/lib.rs b/core/lib/src/lib.rs index f5b1f8eb..a5b8700c 100644 --- a/core/lib/src/lib.rs +++ b/core/lib/src/lib.rs @@ -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) } diff --git a/core/lib/src/local/client.rs b/core/lib/src/local/client.rs index a9dafa6c..1d0f7be7 100644 --- a/core/lib/src/local/client.rs +++ b/core/lib/src/local/client.rs @@ -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 /// diff --git a/core/lib/src/local/mod.rs b/core/lib/src/local/mod.rs index 6b525784..e02c9526 100644 --- a/core/lib/src/local/mod.rs +++ b/core/lib/src/local/mod.rs @@ -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; diff --git a/core/lib/src/local/request.rs b/core/lib/src/local/request.rs index d2687752..0471755b 100644 --- a/core/lib/src/local/request.rs +++ b/core/lib/src/local/request.rs @@ -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
` 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>, response: Response<'c>, diff --git a/core/lib/src/outcome.rs b/core/lib/src/outcome.rs index f338decc..f62637c9 100644 --- a/core/lib/src/outcome.rs +++ b/core/lib/src/outcome.rs @@ -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 { diff --git a/core/lib/src/request/form/error.rs b/core/lib/src/request/form/error.rs index 18df0d76..845f9b67 100644 --- a/core/lib/src/request/form/error.rs +++ b/core/lib/src/request/form/error.rs @@ -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), diff --git a/core/lib/src/request/form/form.rs b/core/lib/src/request/form/form.rs index 5c4c7ef1..611a119e 100644 --- a/core/lib/src/request/form/form.rs +++ b/core/lib/src/request/form/form.rs @@ -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`. 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. diff --git a/core/lib/src/request/form/form_items.rs b/core/lib/src/request/form/form_items.rs index 459c6e5c..21e19f61 100644 --- a/core/lib/src/request/form/form_items.rs +++ b/core/lib/src/request/form/form_items.rs @@ -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 } diff --git a/core/lib/src/request/form/from_form.rs b/core/lib/src/request/form/from_form.rs index f3955366..507cd54a 100644 --- a/core/lib/src/request/form/from_form.rs +++ b/core/lib/src/request/form/from_form.rs @@ -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 /// diff --git a/core/lib/src/request/form/from_form_value.rs b/core/lib/src/request/form/from_form_value.rs index a1d2e752..6c0b42f2 100644 --- a/core/lib/src/request/form/from_form_value.rs +++ b/core/lib/src/request/form/from_form_value.rs @@ -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._ /// diff --git a/core/lib/src/request/from_request.rs b/core/lib/src/request/from_request.rs index b648efba..2bf1e8f3 100644 --- a/core/lib/src/request/from_request.rs +++ b/core/lib/src/request/from_request.rs @@ -66,26 +66,26 @@ impl IntoOutcome for Result { /// /// # 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` and -/// `Option` 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` and `Option` 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` to catch /// `Forward`s. /// @@ -96,45 +96,40 @@ impl IntoOutcome for Result { /// /// * **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._ diff --git a/core/lib/src/request/param.rs b/core/lib/src/request/param.rs index 18239bf8..07453939 100644 --- a/core/lib/src/request/param.rs +++ b/core/lib/src/request/param.rs @@ -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 { /// 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 ``, 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 ``, 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 /// diff --git a/core/lib/src/request/request.rs b/core/lib/src/request/request.rs index 1f4af53d..84cbb783 100644 --- a/core/lib/src/request/request.rs +++ b/core/lib/src/request/request.rs @@ -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
` 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::(); + /// # }); /// ``` /// /// 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::>()?; + /// # type Pool = usize; + /// # Request::example(Method::Get, "/uri", |request| { + /// let pool = request.guard::>(); + /// # }); /// ``` #[inline(always)] pub fn guard<'a, T: FromRequest<'a, 'r>>(&'a self) -> Outcome { @@ -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::("z")` will attempt to parse `"zebra"` as - /// type `T`. #[inline] pub fn get_query_value<'a, T>(&'a self, key: &str) -> Option> where T: FromFormValue<'a> diff --git a/core/lib/src/request/state.rs b/core/lib/src/request/state.rs index 4b539052..7bb9b2ad 100644 --- a/core/lib/src/request/state.rs +++ b/core/lib/src/request/state.rs @@ -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` 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` 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 = (); diff --git a/core/lib/src/response/flash.rs b/core/lib/src/response/flash.rs index f970cb6d..f77fea03 100644 --- a/core/lib/src/response/flash.rs +++ b/core/lib/src/response/flash.rs @@ -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 { 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 { /// 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 { diff --git a/core/lib/src/response/mod.rs b/core/lib/src/response/mod.rs index 9230a4b6..ebec2f9b 100644 --- a/core/lib/src/response/mod.rs +++ b/core/lib/src/response/mod.rs @@ -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; diff --git a/core/lib/src/response/named_file.rs b/core/lib/src/response/named_file.rs index 04a446e0..60375abd 100644 --- a/core/lib/src/response/named_file.rs +++ b/core/lib/src/response/named_file.rs @@ -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)?; diff --git a/core/lib/src/response/responder.rs b/core/lib/src/response/responder.rs index 3bd7b4c5..93c30766 100644 --- a/core/lib/src/response/responder.rs +++ b/core/lib/src/response/responder.rs @@ -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 /// diff --git a/core/lib/src/response/response.rs b/core/lib/src/response/response.rs index e36446ce..bb081e6e 100644 --- a/core/lib/src/response/response.rs +++ b/core/lib/src/response/response.rs @@ -98,19 +98,19 @@ impl fmt::Debug for Body { /// 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
`. - /// 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
`. - /// 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, @@ -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
`. 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
`. 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
`. This includes `Header` itself, - /// [`ContentType`](/rocket/http/struct.ContentType.html) and - /// [`hyper::header` types](/rocket/http/hyper/header/index.html). + /// any type implements `Into
`. 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 /// diff --git a/core/lib/src/rocket.rs b/core/lib/src/rocket.rs index 438374cb..70b7be05 100644 --- a/core/lib/src/rocket.rs +++ b/core/lib/src/rocket.rs @@ -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` 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` 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 diff --git a/scripts/bump_version.sh b/scripts/bump_version.sh index 88c50ee7..8beffc8b 100755 --- a/scripts/bump_version.sh +++ b/scripts/bump_version.sh @@ -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