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
@@ -2,109 +2,281 @@
 #define __OPKELE_OAUTH_CONSUMER_H
 
 #include <string>
 #include <opkele/types.h>
 #include <opkele/oauth.h>
 #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);
 	};
 
 	class simple_provider_endpoints : public basic_provider_endpoints {
 	    public:
 		service_endpoint_t sep_request_token;
 		service_endpoint_t sep_authorize_user;
 		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,
 			oauth_method_t ams=oauth_post_body,
 			oauth_method_t amr=oauth_auth_header )
 		    : sep_request_token(rt,sm,ams),
 		    sep_authorize_user(au,sm,oauth_url_query),
 		    sep_access_token(at,sm,ams),
@@ -116,16 +288,22 @@ namespace opkele {
 		service_endpoint_t& get_url_endpoint(service_endpoint_t& sep,
 			const string& url) const;
 	};
 
 	class simple_consumer : public basic_consumer {
 	    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) { }
 
 		const basic_provider_endpoints& get_endpoints() const;
 		const string allocate_nonce(time_t ts);
 	};