Skip to content

Commit

Permalink
Clean up docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@ramosbugs
ramosbugs committed Jul 12, 2022
1 parent a463055 commit ed70202
Showing 1 changed file with 30 additions and 34 deletions.
64 changes: 30 additions & 34 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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`]**
//!
Expand All @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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 <https://tools.ietf.org/html/rfc6749#section-4.1.3>.
///
pub fn exchange_code(&self, code: AuthorizationCode) -> CodeTokenRequest<TE, TR, TT> {
CodeTokenRequest {
Expand All @@ -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 <https://tools.ietf.org/html/rfc6749#section-4.3.2>.
///
pub fn exchange_password<'a, 'b>(
&'a self,
Expand All @@ -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 <https://tools.ietf.org/html/rfc6749#section-4.4.2>.
///
pub fn exchange_client_credentials(&self) -> ClientCredentialsTokenRequest<TE, TR, TT> {
ClientCredentialsTokenRequest {
Expand All @@ -838,7 +834,7 @@ where
///
/// Exchanges a refresh token for an access token
///
/// See https://tools.ietf.org/html/rfc6749#section-6
/// See <https://tools.ietf.org/html/rfc6749#section-6>.
///
pub fn exchange_refresh_token<'a, 'b>(
&'a self,
Expand All @@ -861,7 +857,7 @@ where

///
/// Perform a device authorization request as per
/// https://tools.ietf.org/html/rfc8628#section-3.1
/// <https://tools.ietf.org/html/rfc8628#section-3.1>.
///
pub fn exchange_device_code(
&self,
Expand All @@ -882,7 +878,7 @@ where

///
/// Perform a device access token request as per
/// https://tools.ietf.org/html/rfc8628#section-3.4
/// <https://tools.ietf.org/html/rfc8628#section-3.4>.
///
pub fn exchange_device_access_token<'a, 'b, 'c, EF>(
&'a self,
Expand Down Expand Up @@ -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 <https://tools.ietf.org/html/rfc6749#section-4.1.3>.
///
#[derive(Debug)]
pub struct CodeTokenRequest<'a, TE, TR, TT>
Expand Down Expand Up @@ -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 <https://tools.ietf.org/html/rfc6749#section-6>.
///
#[derive(Debug)]
pub struct RefreshTokenRequest<'a, TE, TR, TT>
Expand Down Expand Up @@ -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 <https://tools.ietf.org/html/rfc6749#section-4.3>.
///
#[derive(Debug)]
pub struct PasswordTokenRequest<'a, TE, TR, TT>
Expand Down Expand Up @@ -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 <https://tools.ietf.org/html/rfc6749#section-4.4>.
///
#[derive(Debug)]
pub struct ClientCredentialsTokenRequest<'a, TE, TR, TT>
Expand Down Expand Up @@ -1704,7 +1700,7 @@ where
///
/// A request to introspect an access token.
///
/// See https://tools.ietf.org/html/rfc7662#section-2.1
/// See <https://tools.ietf.org/html/rfc7662#section-2.1>.
///
#[derive(Debug)]
pub struct IntrospectionRequest<'a, TE, TIR, TT>
Expand Down Expand Up @@ -1734,7 +1730,7 @@ where
///
/// Sets the optional token_type_hint parameter.
///
/// See: https://tools.ietf.org/html/rfc7662#section-2.1
/// See <https://tools.ietf.org/html/rfc7662#section-2.1>.
///
/// OPTIONAL. A hint about the type of the token submitted for
/// introspection. The protected resource MAY pass this parameter to
Expand Down Expand Up @@ -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 <https://tools.ietf.org/html/rfc8628#section-3.1>.
///
#[derive(Debug)]
pub struct DeviceAuthorizationRequest<'a, TE>
Expand Down Expand Up @@ -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 <https://tools.ietf.org/html/rfc8628#section-3.4>.
///
#[derive(Clone)]
pub struct DeviceAccessTokenRequest<'a, 'b, TR, TT, EF>
Expand Down Expand Up @@ -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`.
Expand All @@ -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>;
Expand Down

0 comments on commit ed70202

Please sign in to comment.