1 files changed, 180 insertions, 2 deletions

diff --git a/include/opkele/oauth/consumer.h b/include/opkele/oauth/consumer.h
index eb4f753..3ad18a2 100644
--- a/include/opkele/oauth/consumer.h
+++ b/include/opkele/oauth/consumer.h
@@ -9,2 +9,5 @@
 namespace opkele {
+    /**
+     * @brief OAuth support namespace
+     */
     namespace oauth {
@@ -12,4 +15,21 @@ namespace opkele {
 
+        /**
+         * oauth parameter passing method
+         */
         enum oauth_method_t {
-            oauth_auth_header, oauth_post_body, oauth_url_query,
+            /**
+             * via WWW-Authenticate header
+             */
+            oauth_auth_header,
+            /**
+             * via POST body
+             */
+            oauth_post_body,
+            /**
+             * via GET query string
+             */
+            oauth_url_query,
+            /**
+             * default method
+             */
             oauth_method_default = oauth_auth_header
@@ -17,5 +37,17 @@ namespace opkele {
 
+        /**
+         * Service endpoint description
+         */
         struct service_endpoint_t {
+            /**
+             * endpoint URI
+             */
             string url;
+            /**
+             * signature method
+             */
             string signature_method;
+            /**
+             * OAuth parameter passing method
+             */
             oauth_method_t oauth_method;
@@ -23,2 +55,7 @@ namespace opkele {
             service_endpoint_t() : oauth_method(oauth_method_default) { }
+            /**
+             * @param u endpoint URI
+             * @param sm signature method
+             * @param om OAuth parameter passing method
+             */
             service_endpoint_t(const string& u,const string& sm,oauth_method_t om=oauth_method_default)
@@ -27,2 +64,5 @@ namespace opkele {
 
+        /**
+         * Base class for OAuth provider endpoints description
+         */
         class basic_provider_endpoints {
@@ -31,7 +71,26 @@ namespace opkele {
                 virtual ~basic_provider_endpoints() { }
-                
+
+                /**
+                 * Retrieve endpoint for obtaining an unauthorized request token
+                 * @return service endpoint description
+                 */
                 virtual const service_endpoint_t& get_request_token_endpoint() const = 0;
+                /**
+                 * Retrieve endpoint for user authorization
+                 * @return service endpoint description
+                 */
                 virtual const service_endpoint_t& get_authorize_user_endpoint() const = 0;
+                /**
+                 * Retrieve endpoint for obtaining an access token from the
+                 * authorized request token
+                 * @return service endpoint description
+                 */
                 virtual const service_endpoint_t& get_access_token_endpoint() const = 0;
 
+                /**
+                 * Make up an endpoint description give an URI
+                 * @param sep reference to the service endpoint description object to fill in
+                 * @param url endpoint URL
+                 * @return reference to sep
+                 */
                 virtual service_endpoint_t& get_url_endpoint(service_endpoint_t& sep,
@@ -40,10 +99,32 @@ namespace opkele {
 
+        /**
+         * HTTP request information
+         */
         struct http_request_t {
+            /**
+             * WWW-Authenticate header
+             */
             string authorize_header;
+            /**
+             * HTTP method
+             */
             string method;
+            /**
+             * Target URL
+             */
             string url;
+            /**
+             * POST body
+             */
             string body;
 
+            /**
+             * curl-ready headers
+             */
             util::curl_slist_t _curl_headers_list;
 
+            /**
+             * @param m HTTP method
+             * @param u target URL
+             */
             http_request_t(const string& m,const string& u)
@@ -51,2 +132,5 @@ namespace opkele {
 
+            /**
+             * Set relevant curl handle options
+             */
             void setup_curl(CURL *curl);
@@ -54,6 +138,15 @@ namespace opkele {
 
+        /**
+         * OAuth consumer base class
+         */
         class basic_consumer {
             public:
+                /**
+                 * Consumer token
+                 */
                 token_t consumer_token;
 
+                /**
+                 * @param ct consumer token
+                 */
                 basic_consumer(const token_t& ct)
@@ -62,9 +155,45 @@ namespace opkele {
 
+                /**
+                 * Retrieve reference to the provider endpoints description object
+                 * @return reference to the provider endpoints description object
+                 */
                 virtual const basic_provider_endpoints& get_endpoints() const = 0;
+                /**
+                 * Allocate nonce
+                 * @param ts request timestamp
+                 * @return nonce string
+                 */
                 virtual const string allocate_nonce(time_t ts) = 0;
 
+                /**
+                 * Obtain an unauthorized request token
+                 * @return request token
+                 */
                 token_t get_request_token();
+                /**
+                 * Retrieve the user authorization URL
+                 * @param rt unauthorized request token
+                 * @param callback callback URL to be passed to oauth provider
+                 * to redirect user to upon authorization
+                 * @return user authorization URL
+                 */
                 const string get_authorize_url(const token_t& rt,const string& callback="");
+                /**
+                 * Trade an authorized request token for an access token
+                 * @param rt authorized request token
+                 * @return access token
+                 */
                 token_t get_access_token(const token_t& rt);
 
+                /**
+                 * Prepare http request parameters
+                 * @param req request description to fill in
+                 * @param qf query string parameters
+                 * @param pf post body parameters
+                 * @param om OAuth method
+                 * @param sm signature method
+                 * @param t pointer to the token to use to sign request, if any.
+                 * @param realm authorization realm
+                 * @return reference to req
+                 */
                 http_request_t& prepare_request(
@@ -74,2 +203,12 @@ namespace opkele {
                         const token_t *t=0,const string& realm="");
+                /**
+                 * Prepare http request parameters
+                 * @param req request description to fill in
+                 * @param qf query string parameters
+                 * @param pf post body parameters
+                 * @param sep service endpoint description
+                 * @param t pointer to the token to use to sign request, if any.
+                 * @param realm authorization realm
+                 * @return reference to req
+                 */
                 http_request_t& prepare_request(
@@ -79,2 +218,11 @@ namespace opkele {
                         const token_t *t=0,const string& realm="");
+                /**
+                 * Prepare http request parameters
+                 * @param req request description to fill in
+                 * @param qf query string parameters
+                 * @param pf post body parameters
+                 * @param t pointer to the token to use to sign request, if any.
+                 * @param realm authorization realm
+                 * @return reference to req
+                 */
                 http_request_t& prepare_request(
@@ -84,2 +232,11 @@ namespace opkele {
 
+                /**
+                 * Calculate request signature
+                 * @param method http method
+                 * @param url the url being invoked
+                 * @param fields all request fields (query string, auth header,
+                 * post body)
+                 * @param rt pointer to the request token to be used for
+                 * signing, if any.
+                 */
                 const string signature(
@@ -90,2 +247,9 @@ namespace opkele {
 
+                /**
+                 * Acquire token from an OAuth provider
+                 * @param sep service endpoint description
+                 * @param rt pointer to the request token to use for signing,
+                 * if any
+                 * @return the acquired token
+                 */
                 token_t acquire_token(
@@ -102,2 +266,10 @@ namespace opkele {
 
+                /**
+                 * @param rt request token endpoint URL
+                 * @param au user authorization endpoint URL
+                 * @param at access token endpoint URL
+                 * @param sm signature method
+                 * @param ams authentication method for service endpoints
+                 * @param amr authentication method for resource access
+                 */
                 simple_provider_endpoints(
@@ -123,2 +295,8 @@ namespace opkele {
 
+                /**
+                 * @param eps provider endpoints
+                 * @param ct consumer token
+                 * @see simple_provider_endpoints
+                 * @see token_t
+                 */
                 simple_consumer(const simple_provider_endpoints& eps,