From efbf43302527eb08863f9aaed84bc1c93e98a64d Mon Sep 17 00:00:00 2001 From: Curtis McEnroe Date: Sat, 28 Nov 2015 23:33:58 -0500 Subject: [PATCH] Fill in documentation --- src/client.rs | 14 ++++++++++++-- src/error.rs | 28 +++++++++++++++++++++++++++- src/lib.rs | 9 +++------ src/token.rs | 13 +++++++++++++ 4 files changed, 55 insertions(+), 9 deletions(-) diff --git a/src/client.rs b/src/client.rs index c9291a2..ce04620 100644 --- a/src/client.rs +++ b/src/client.rs @@ -9,6 +9,10 @@ use super::Token; use super::error::{Error, Result, OAuth2Error, OAuth2ErrorCode}; /// OAuth 2.0 client. +/// +/// Performs HTTP requests using the provided `hyper::Client`. +/// +/// See [RFC6749 section 4.1](http://tools.ietf.org/html/rfc6749#section-4.1). pub struct Client { http_client: hyper::Client, @@ -116,13 +120,13 @@ impl Client { } site_constructors!{ - #[doc = "Creates a Google OAuth 2.0 client."] + #[doc = "Creates a Google OAuth 2.0 client.\n\nSee [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/identity/protocols/OAuth2)."] google => ( "https://accounts.google.com/o/oauth2/auth", "https://accounts.google.com/o/oauth2/token" ), - #[doc = "Creates a GitHub OAuth 2.0 client."] + #[doc = "Creates a GitHub OAuth 2.0 client.\n\nSee [OAuth, GitHub API](https://developer.github.com/v3/oauth/)."] github => ( "https://github.com/login/oauth/authorize", "https://github.com/login/oauth/access_token" @@ -130,6 +134,8 @@ impl Client { } /// Constructs an authorization request URI. + /// + /// See [RFC6749 section 4.1.1](http://tools.ietf.org/html/rfc6749#section-4.1.1). pub fn auth_uri(&self, scope: Option<&str>, state: Option<&str>) -> Result { let mut uri = try!(Url::parse(&self.auth_uri)); @@ -195,6 +201,8 @@ impl Client { } /// Requests an access token using an authorization code. + /// + /// See [RFC6749 section 4.1.3](http://tools.ietf.org/html/rfc6749#section-4.1.3). pub fn request_token(&self, code: &str) -> Result { let mut body_pairs = vec![ ("grant_type", "authorization_code"), @@ -208,6 +216,8 @@ impl Client { /// Refreshes an access token. /// + /// See [RFC6749 section 6](http://tools.ietf.org/html/rfc6749#section-6). + /// /// # Panics /// /// Panics if `token` does not contain a `refresh_token`. diff --git a/src/error.rs b/src/error.rs index 47f86bc..61ec1c0 100644 --- a/src/error.rs +++ b/src/error.rs @@ -5,24 +5,50 @@ use rustc_serialize::json; use url; /// OAuth 2.0 error codes. +/// +/// See [RFC6749 section 5.2](http://tools.ietf.org/html/rfc6749#section-5.2). #[derive(Debug)] pub enum OAuth2ErrorCode { + /// The request is missing a required parameter, includes an unsupported parameter value (other + /// than grant type), repeats a parameter, includes multiple credentials, utilizes more than + /// one mechanism for authenticating the client, or is otherwise malformed. InvalidRequest, + + /// Client authentication failed (e.g., unknown client, no client authentication included, or + /// unsupported authentication method). InvalidClient, + + /// The provided authorization grant (e.g., authorization code, resource owner credentials) or + /// refresh token is invalid, expired, revoked, does not match the redirection URI used in the + /// authorization request, or was issued to another client. InvalidGrant, + + /// The authenticated client is not authorized to use this authorization grant type. UnauthorizedClient, + + /// The authorization grant type is not supported by the authorization server. UnsupportedGrantType, + + /// The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the + /// resource owner. InvalidScope, + + /// An unrecognized error code, not defined in RFC6749. Unrecognized(String), } /// OAuth 2.0 error. /// -/// See [RFC6749](http://tools.ietf.org/html/rfc6749#section-5.2). +/// See [RFC6749 section 5.2](http://tools.ietf.org/html/rfc6749#section-5.2). #[derive(Debug)] pub struct OAuth2Error { + /// Error code. pub code: OAuth2ErrorCode, + + /// Human-readable text providing additional information about the error. pub description: Option, + + /// A URI identifying a human-readable web page with information about the error. pub uri: Option, } diff --git a/src/lib.rs b/src/lib.rs index 20b04cb..8f07a80 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -7,6 +7,8 @@ //! [crate]: https://crates.io/crates/inth-oauth2 //! [github]: https://github.com/programble/inth-oauth2 //! +//! Implementation of [RFC6749](http://tools.ietf.org/html/rfc6749). +//! //! ## Providers //! //! `inth_oauth2` can be used with any OAuth 2.0 provider, but provides defaults for a few common @@ -30,12 +32,7 @@ //! ``` //! use inth_oauth2::Client as OAuth2; //! -//! let auth = OAuth2::github( -//! Default::default(), -//! "CLIENT_ID", -//! "CLIENT_SECRET", -//! None -//! ); +//! let auth = OAuth2::github(Default::default(), "CLIENT_ID", "CLIENT_SECRET", None); //! ``` //! //! ### Other diff --git a/src/token.rs b/src/token.rs index 5636904..c3b5c45 100644 --- a/src/token.rs +++ b/src/token.rs @@ -1,12 +1,25 @@ use chrono::{DateTime, UTC}; /// OAuth 2.0 access token. +/// +/// See [RFC6749 section 5](http://tools.ietf.org/html/rfc6749#section-5). #[derive(Debug)] pub struct Token { + /// The access token issued by the authorization server. pub access_token: String, + + /// The type of the token issued. + /// + /// See [RFC6749 section 7.1](http://tools.ietf.org/html/rfc6749#section-7.1). pub token_type: String, + + /// The expiry time of the access token. pub expires: Option>, + + /// The refresh token, which can be used to obtain new access tokens. pub refresh_token: Option, + + /// The scope of the access token. pub scope: Option, }