Fill in documentation

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<String> {
         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<Token> {
         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`.

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<String>,
+
+    /// A URI identifying a human-readable web page with information about the error.
     pub uri: Option<String>,
 }
 

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(
+//! let auth = OAuth2::github(Default::default(), "CLIENT_ID", "CLIENT_SECRET", None);
-//!     Default::default(),
-//!     "CLIENT_ID",
-//!     "CLIENT_SECRET",
-//!     None
-//! );
 //! ```
 //!
 //! ### Other

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<DateTime<UTC>>,
+
+    /// The refresh token, which can be used to obtain new access tokens.
     pub refresh_token: Option<String>,
+
+    /// The scope of the access token.
     pub scope: Option<String>,
 }