From ed70202a90609ca306233b34047316260434b859 Mon Sep 17 00:00:00 2001 From: "David A. Ramos" Date: Mon, 11 Jul 2022 18:25:43 -0700 Subject: [PATCH] Clean up docs --- src/lib.rs | 64 +++++++++++++++++++++++++----------------------------- 1 file changed, 30 insertions(+), 34 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 12c7257..e5d2dac 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -8,7 +8,7 @@ //! * [Importing `oauth2`: selecting an HTTP client interface](#importing-oauth2-selecting-an-http-client-interface) //! * [Getting started: Authorization Code Grant w/ PKCE](#getting-started-authorization-code-grant-w-pkce) //! * [Example: Synchronous (blocking) API](#example-synchronous-blocking-api) -//! * [Example: Async/Await API](#example-asyncawait-api) +//! * [Example: Asynchronous API](#example-asynchronous-api) //! * [Implicit Grant](#implicit-grant) //! * [Resource Owner Password Credentials Grant](#resource-owner-password-credentials-grant) //! * [Client Credentials Grant](#client-credentials-grant) @@ -20,24 +20,18 @@ //! //! This library offers a flexible HTTP client interface with two modes: //! * **Synchronous (blocking)** -//! -//! The synchronous interface is available for any combination of feature flags. -//! -//! Example import in `Cargo.toml`: -//! ```toml -//! oauth2 = "4" -//! ``` +//! * **Asynchronous** //! //! For the HTTP client modes described above, the following HTTP client implementations can be //! used: //! * **[`reqwest`]** //! -//! The `reqwest` HTTP client supports both modes. By default, `reqwest` 0.11 is enabled, -//! which supports the synchronous and asynchronous `futures` 0.3 APIs. +//! The `reqwest` HTTP client supports both the synchronous and asynchronous modes and is enabled +//! by default. //! //! Synchronous client: [`reqwest::http_client`] //! -//! Async/await `futures` 0.3 client: [`reqwest::async_http_client`] +//! Asynchronous client: [`reqwest::async_http_client`] //! //! * **[`curl`]** //! @@ -49,16 +43,18 @@ //! * **[`ureq`]** //! //! The `ureq` HTTP client is a simple HTTP client with minimal dependencies. It only supports -//! the synchronous HTTP client mode and can be enabled in `Cargo.toml` via the `ureq` feature flag. +//! the synchronous HTTP client mode and can be enabled in `Cargo.toml` via the `ureq` feature +//! flag. //! //! * **Custom** //! //! In addition to the clients above, users may define their own HTTP clients, which must accept //! an [`HttpRequest`] and return an [`HttpResponse`] or error. Users writing their own clients //! may wish to disable the default `reqwest` dependency by specifying -//! `default-features = false` in `Cargo.toml`: +//! `default-features = false` in `Cargo.toml` (replacing `...` with the desired version of this +//! crate): //! ```toml -//! oauth2 = { version = "4", default-features = false } +//! oauth2 = { version = "...", default-features = false } //! ``` //! //! Synchronous HTTP clients should implement the following trait: @@ -67,7 +63,7 @@ //! where RE: std::error::Error + 'static //! ``` //! -//! Async/await HTTP clients should implement the following trait: +//! Asynchronous HTTP clients should implement the following trait: //! ```rust,ignore //! FnOnce(HttpRequest) -> F //! where @@ -150,9 +146,9 @@ //! # } //! ``` //! -//! ## Example: Async/Await API +//! ## Example: Asynchronous API //! -//! One can use async/await as follows: +//! The example below uses async/await: //! //! ```rust,no_run //! use anyhow; @@ -776,7 +772,7 @@ where /// Acquires ownership of the `code` because authorization codes may only be used once to /// retrieve an access token from the authorization server. /// - /// See https://tools.ietf.org/html/rfc6749#section-4.1.3 + /// See . /// pub fn exchange_code(&self, code: AuthorizationCode) -> CodeTokenRequest { CodeTokenRequest { @@ -795,7 +791,7 @@ where /// /// Requests an access token for the *password* grant type. /// - /// See https://tools.ietf.org/html/rfc6749#section-4.3.2 + /// See . /// pub fn exchange_password<'a, 'b>( &'a self, @@ -821,7 +817,7 @@ where /// /// Requests an access token for the *client credentials* grant type. /// - /// See https://tools.ietf.org/html/rfc6749#section-4.4.2 + /// See . /// pub fn exchange_client_credentials(&self) -> ClientCredentialsTokenRequest { ClientCredentialsTokenRequest { @@ -838,7 +834,7 @@ where /// /// Exchanges a refresh token for an access token /// - /// See https://tools.ietf.org/html/rfc6749#section-6 + /// See . /// pub fn exchange_refresh_token<'a, 'b>( &'a self, @@ -861,7 +857,7 @@ where /// /// Perform a device authorization request as per - /// https://tools.ietf.org/html/rfc8628#section-3.1 + /// . /// pub fn exchange_device_code( &self, @@ -882,7 +878,7 @@ where /// /// Perform a device access token request as per - /// https://tools.ietf.org/html/rfc8628#section-3.4 + /// . /// pub fn exchange_device_access_token<'a, 'b, 'c, EF>( &'a self, @@ -1204,7 +1200,7 @@ pub struct HttpResponse { /// /// A request to exchange an authorization code for an access token. /// -/// See https://tools.ietf.org/html/rfc6749#section-4.1.3. +/// See . /// #[derive(Debug)] pub struct CodeTokenRequest<'a, TE, TR, TT> @@ -1335,7 +1331,7 @@ where /// /// A request to exchange a refresh token for an access token. /// -/// See https://tools.ietf.org/html/rfc6749#section-6. +/// See . /// #[derive(Debug)] pub struct RefreshTokenRequest<'a, TE, TR, TT> @@ -1458,7 +1454,7 @@ where /// /// A request to exchange resource owner credentials for an access token. /// -/// See https://tools.ietf.org/html/rfc6749#section-4.3. +/// See . /// #[derive(Debug)] pub struct PasswordTokenRequest<'a, TE, TR, TT> @@ -1584,7 +1580,7 @@ where /// /// A request to exchange client credentials for an access token. /// -/// See https://tools.ietf.org/html/rfc6749#section-4.4. +/// See . /// #[derive(Debug)] pub struct ClientCredentialsTokenRequest<'a, TE, TR, TT> @@ -1704,7 +1700,7 @@ where /// /// A request to introspect an access token. /// -/// See https://tools.ietf.org/html/rfc7662#section-2.1 +/// See . /// #[derive(Debug)] pub struct IntrospectionRequest<'a, TE, TIR, TT> @@ -1734,7 +1730,7 @@ where /// /// Sets the optional token_type_hint parameter. /// - /// See: https://tools.ietf.org/html/rfc7662#section-2.1 + /// See . /// /// OPTIONAL. A hint about the type of the token submitted for /// introspection. The protected resource MAY pass this parameter to @@ -2131,7 +2127,7 @@ where /// /// The request for a set of verification codes from the authorization server. /// -/// See https://tools.ietf.org/html/rfc8628#section-3.1. +/// See . /// #[derive(Debug)] pub struct DeviceAuthorizationRequest<'a, TE> @@ -2251,7 +2247,7 @@ where /// /// The request for an device access token from the authorization server. /// -/// See https://tools.ietf.org/html/rfc8628#section-3.4. +/// See . /// #[derive(Clone)] pub struct DeviceAccessTokenRequest<'a, 'b, TR, TT, EF> @@ -2722,7 +2718,7 @@ where /// /// OPTIONAL. A JSON string containing a space-separated list of /// scopes associated with this token, in the format described in - /// [Section 3.3 of OAuth 2.0](https://tools.ietf.org/html/rfc7662#section-3.3). + /// [Section 3.3 of RFC 7662](https://tools.ietf.org/html/rfc7662#section-3.3). /// If included in the response, /// this space-delimited field is parsed into a `Vec` of individual scopes. If omitted from /// the response, this field is `None`. @@ -2739,8 +2735,8 @@ where /// fn username(&self) -> Option<&str>; /// - /// OPTIONAL. Type of the token as defined in [Section 5.1](https://tools.ietf.org/html/rfc7662#section-5.1) of OAuth - /// 2.0 [RFC6749]. + /// OPTIONAL. Type of the token as defined in + /// [Section 5.1 of RFC 7662](https://tools.ietf.org/html/rfc7662#section-5.1). /// Value is case insensitive and deserialized to the generic `TokenType` parameter. /// fn token_type(&self) -> Option<&TT>;