user: Extend github_access_token() documentation

Author: Turbo87

src/user/mod.rs

@@ -150,6 +150,33 @@ pub fn github_authorize(req: &mut Request) -> CargoResult<Response> {
 }
 
 /// Handles the `GET /authorize` route.
+///
+/// This route is called from the GitHub API OAuth flow after the user accepted or rejected
+/// the data access permissions. It will check the `state` parameter and then call the GitHub API
+/// to exchange the temporary `code` for an API token. The API token is returned together with
+/// the corresponding user information.
+///
+/// see https://developer.github.com/v3/oauth/#github-redirects-back-to-your-site
+///
+/// ## Query Parameters
+///
+/// - `code` – temporary code received from the GitHub API  **(Required)**
+/// - `state` – state parameter received from the GitHub API  **(Required)**
+///
+/// ## Response Body Example
+///
+/// ```json
+/// {
+///     "api_token": "b84a63c4ea3fcb4ac84",
+///     "user": {
+///         "email": "[email protected]",
+///         "name": "Foo Bar",
+///         "login": "foobar",
+///         "avatar": "https://avatars.githubusercontent.com/u/1234",
+///         "url": null
+///     }
+/// }
+/// ```
 pub fn github_access_token(req: &mut Request) -> CargoResult<Response> {
     // Parse the url query
     let mut query = req.query();