From e859f435a17ad6db7cb9fb8823417510f7d29a16 Mon Sep 17 00:00:00 2001
From: Alex Bilbie <alex@alexbilbie.com>
Date: Tue, 14 Aug 2012 16:28:40 +0100
Subject: [PATCH] Added docblocks for the database interface

---
 src/Oauth2/Resource/Database.php | 51 +++++++++++++++++++++++++++++++-
 1 file changed, 50 insertions(+), 1 deletion(-)

diff --git a/src/Oauth2/Resource/Database.php b/src/Oauth2/Resource/Database.php
index a6ff8a2a..ac91bfa9 100644
--- a/src/Oauth2/Resource/Database.php
+++ b/src/Oauth2/Resource/Database.php
@@ -4,7 +4,56 @@ namespace Oauth2\Resource;
 
 interface Database
 {
+	/**
+	 * Validate an access token and return the session details.
+	 * 
+	 * Database query:
+	 * 
+	 * <code>
+	 * SELECT id, owner_type, owner_id FROM oauth_sessions WHERE access_token =
+	 *  $accessToken AND stage = 'granted' AND
+	 *  access_token_expires > UNIX_TIMESTAMP(now())
+	 * </code>
+     * 
+     * Response:
+     * 
+     * <code>
+     * Array
+     * (
+     *     [id] => (int) The session ID
+     *     [owner_type] => (string) The session owner type
+     *     [owner_id] => (string) The session owner's ID
+     * )
+     * </code>
+	 * 
+	 * @param  string     $accessToken The access token
+	 * @return array|bool              Return an array on success or false on failure
+	 */
 	public function validateAccessToken($accessToken);
-	
+
+	/**
+	 * Returns the scopes that the session is authorised with.
+	 * 
+	 * Database query:
+	 * 
+	 * <code>
+	 * SELECT scope FROM oauth_session_scopes WHERE access_token =
+	 *  '291dca1c74900f5f252de351e0105aa3fc91b90b'
+	 * </code>
+	 * 
+	 * Response:
+	 * 
+	 * <code>
+	 * Array
+	 * (
+	 * 		[0] => (string) A scope
+	 *   	[1]	=> (string) Another scope
+	 *    	...
+	 * )
+	 * </code>
+	 * 
+	 * @param  int   $sessionId The session ID
+	 * @return array            A list of scopes
+	 */
 	public function sessionScopes($sessionId);
 }
\ No newline at end of file