1 files changed, 75 insertions, 2 deletions

diff --git a/include/opkele/basic_op.h b/include/opkele/basic_op.h
index 4daed02..a0f0af0 100644
--- a/include/opkele/basic_op.h
+++ b/include/opkele/basic_op.h
@@ -1,132 +1,205 @@
 #ifndef __OPKELE_BASIC_OP_H
 #define __OPKELE_BASIC_OP_H
 
 #include <string>
 #include <opkele/types.h>
 #include <opkele/extension.h>
 
 namespace opkele {
     using std::string;
 
     class basic_OP {
         public:
+            /**
+             * The request mode for the request being processed
+             */
             mode_t mode;
+            /**
+             * association used in transaction. reset in case of dumb operation
+             */
             assoc_t assoc;
+            /**
+             * true if the request is openid2 request
+             */
             bool openid2;
+            /**
+             * The return_to RP endpoint
+             */
             string return_to;
+            /**
+             * The realm we authenticate for
+             */
             string realm;
+            /**
+             * Claimed identifier
+             */
             string claimed_id;
+            /**
+             * The OP-Local identifier
+             */
             string identity;
+            /**
+             * The invalidate handle for the reply request
+             */
             string invalidate_handle;
 
             void reset_vars();
 
+            /**
+             * @name Request information access
+             * Setting and retrieval of the information pertaining to the request being processed
+             * @{
+             */
+            /**
+             * Check if the RP expects us to get back to them.
+             * @return true if RP supplied return_to URL
+             */
             bool has_return_to() const;
+            /**
+             * Find out where the RP is waiting for us.
+             * @return the return_to URL supplied
+             * @throw no_return_to if no return_to is supplied with the request
+             */
             const string& get_return_to() const;
 
+            /**
+             * Find out what realm we are authenticating user for
+             * @return the realm
+             */
             const string& get_realm() const;
 
+            /**
+             * Check if request is about identity
+             * @return true if so
+             */
             bool has_identity() const;
+            /**
+             * Get claimed identifier supplied with the request
+             * @return claimed identifier
+             * @throw non_identity if request is not about identity
+             */
             const string& get_claimed_id() const;
+            /**
+             * Get the identity (OP-Local identifier) being confirmed
+             * @return identity
+             * @throw non_identity if request is not about identity
+             */
             const string& get_identity() const;
 
+            /**
+             * Is identifier supposed to be selected on our side?
+             * @return true if identity is a special identifier select URI
+             */
             bool is_id_select() const;
 
-            void select_identity(const string& c,const string& i);
-            void set_claimed_id(const string& c);
+            /**
+             * Select the identity for identifier select request
+             * @param cid claimed identifier
+             * @param lid local identifier
+             */
+            void select_identity(const string& cid,const string& lid);
+            /**
+             * Set claimed identifier (for instance if it's supposed to have
+             * fragment part)
+             * @param cid claimed identifier
+             */
+            void set_claimed_id(const string& cid);
+            /**
+             * @}
+             */
 
             /** @name OpenID operations
              * @{
              */
             /**
              * Establish association with RP
              * @param oum reply message
              * @param inm request message
              */
             basic_openid_message& associate(
                     basic_openid_message& oum,
                     const basic_openid_message& inm);
 
             /**
              * Parse the checkid_* request. The function parses input message,
              * retrieves the information needed for further processing,
              * verifies what can be verified at this stage.
              * @param inm incoming OpenID message
              * @param ext extension/chain of extensions supported
              */
             void checkid_(const basic_openid_message& inm,extension_t *ext=0);
             /**
              * Build and sign a positive assertion message
              * @param om outpu OpenID message
              * @param ext extension/chain of extensions supported
              * @return reference to om
              */
             basic_openid_message& id_res(basic_openid_message& om,
                     extension_t *ext=0);
             /**
              * Build a 'cancel' negative assertion
              * @param om output OpenID message
              * @return reference to om
              */
             basic_openid_message& cancel(basic_openid_message& om);
             /**
              * Build an 'error' reply
              * @param om output OpenID message
              * @param error a human-readable message indicating the cause
              * @param contact contact address for the server administrator (can be empty)
              * @param reference a reference token (can be empty)
              * @return reference to om
              */
             basic_openid_message& error(basic_openid_message& om,
                     const string& error,const string& contact,
                     const string& reference );
             /**
              * Build a setup_needed reply to checkid_immediate request
              * @param oum output OpenID message
              * @param inm incoming OpenID request being processed
              * @return reference to oum
              */
             basic_openid_message& setup_needed(
                     basic_openid_message& oum,const basic_openid_message& inm);
 
             /**
              * Process check_authentication request
              * @param oum output OpenID message
              * @param inm incoming request
              * @return reference to oum
              */
             basic_openid_message& check_authentication(
                     basic_openid_message& oum,const basic_openid_message& inm);
             /**
              * @}
              */
 
             /**
              * Verify return_to url. The default implementation checks whether
              * return_to URI matches the realm
              * @throw bad_realm in case of invalid realm
              * @throw bad_return_to if return_to doesn't match the realm
              * @see verify_op::verify_return_to()
              */
             virtual void verify_return_to();
 
             /**
              * @name Global persistent store API
              * These functions are related to the associations with RPs storage
              * and retrieval and nonce management.
              * @{
              */
             /**
              * Allocate association.
              * @param type association type
              * @param kl association key length
              * @param sl true if the association is stateless
              * @return association object
              */
             virtual assoc_t alloc_assoc(const string& type,size_t kl,bool sl) = 0;
             /**
              * Retrieve valid unexpired association
              * @param handle association handle
              * @return association object
              */
             virtual assoc_t retrieve_assoc(const string& handle) = 0;