slight doxygenization of OAuth part

Signed-off-by: Michael Krelin <hacker@klever.net>

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
@@ -7,87 +7,251 @@
 #include <opkele/curl.h>
 
 namespace opkele {
+    /**
+     * @brief OAuth support namespace
+     */
     namespace oauth {
         using std::string;
 
+        /**
+         * 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
         };
 
+        /**
+         * 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;
 
             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)
                 : url(u), signature_method(sm), oauth_method(om) { }
         };
 
+        /**
+         * Base class for OAuth provider endpoints description
+         */
         class basic_provider_endpoints {
             public:
 
                 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,
                         const string& url) const = 0;
         };
 
+        /**
+         * 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)
                 : method(m), url(u) { }
 
+            /**
+             * Set relevant curl handle options
+             */
             void setup_curl(CURL *curl);
         };
 
+        /**
+         * OAuth consumer base class
+         */
         class basic_consumer {
             public:
+                /**
+                 * Consumer token
+                 */
                 token_t consumer_token;
 
+                /**
+                 * @param ct consumer token
+                 */
                 basic_consumer(const token_t& ct)
                     : consumer_token(ct) { }
                 virtual ~basic_consumer() { }
 
+                /**
+                 * 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(
                         http_request_t& req,
                         const basic_fields& qf,const basic_fields& pf,
                         oauth_method_t om,const string& sm,
                         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(
                         http_request_t& req,
                         const basic_fields& qf,const basic_fields& pf,
                         const service_endpoint_t& sep,
                         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(
                         http_request_t& req,
                         const basic_fields& qf,const basic_fields& pf,
                         const token_t *t=0,const string& realm="");
 
+                /**
+                 * 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(
                         const string& method,
                         const string& url,
                         const basic_fields& fields,
                         const token_t* rt=0);
 
+                /**
+                 * 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(
                         const service_endpoint_t& sep,
                         const token_t* rt=0);
@@ -100,6 +264,14 @@ namespace opkele {
                 service_endpoint_t sep_access_token;
                 service_endpoint_t sep_generic;
 
+                /**
+                 * @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(
                         const string& rt,const string& au,const string& at,
                         const string& sm,
@@ -121,6 +293,12 @@ namespace opkele {
             public:
                 simple_provider_endpoints peps;
 
+                /**
+                 * @param eps provider endpoints
+                 * @param ct consumer token
+                 * @see simple_provider_endpoints
+                 * @see token_t
+                 */
                 simple_consumer(const simple_provider_endpoints& eps,
                         const token_t& ct)
                     : basic_consumer(ct), peps(eps) { }