3 files changed, 21 insertions, 0 deletions

diff --git a/include/opkele/basic_op.h b/include/opkele/basic_op.h
index a0f0af0..0e3231d 100644
--- a/include/opkele/basic_op.h
+++ b/include/opkele/basic_op.h
@@ -1,138 +1,141 @@
 #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;
 
+    /**
+     * Implementation of basic OP functionality
+     */
     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;
 
             /**
              * 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);
diff --git a/include/opkele/extension.h b/include/opkele/extension.h
index 37bcb90..38f61e3 100644
--- a/include/opkele/extension.h
+++ b/include/opkele/extension.h
@@ -1,61 +1,69 @@
 #ifndef __OPKELE_EXTENSION_H
 #define __OPKELE_EXTENSION_H
 
 /**
  * @file
  * @brief extensions framework basics
  */
 
 #include <opkele/opkele-config.h>
 #include <opkele/types.h>
 
 namespace opkele {
 
     /**
      * OpenID extension hooks base class
      */
     class extension_t {
         public:
 
             virtual ~extension_t() { }
 
             /**
              * hook called by RP before submitting the message to OP.
              * @param om openid message to be submit
              */
             virtual void rp_checkid_hook(basic_openid_message& om);
 
             /**
              * hook called by RP after verifying information received from OP.
              * @param om openid message received
              * @param sp signed part of the message
              */
             virtual void rp_id_res_hook(const basic_openid_message& om,
                     const basic_openid_message& sp);
 
             /**
              * hook called by OP after parsing incoming message
              * @param inm message received from RP
              */
             virtual void op_checkid_hook(const basic_openid_message& inm);
             /**
              * hook called by OP before signing the reply to RP
              * @param oum message to be sent to RP
              */
             virtual void op_id_res_hook(basic_openid_message& oum);
 
+            /**
+             * @name deprecated hooks, used by the deprecated consumer_t and
+             * server_t implementations
+             * @{
+             */
             virtual void checkid_hook(basic_openid_message& om) OPKELE_DEPRECATE;
             virtual void id_res_hook(const basic_openid_message& om,
                     const basic_openid_message& sp) OPKELE_DEPRECATE;
             virtual void checkid_hook(const basic_openid_message& inm,basic_openid_message& oum);
+            /**
+             * @}
+             */
 
             /**
              * Casts the object to pointer to itself. For convenient passing
              * of pointer.
              */
             operator extension_t*(void) { return this; }
     };
 
 }
 
 #endif /* __OPKELE_EXTENSION_H */
diff --git a/include/opkele/verify_op.h b/include/opkele/verify_op.h
index 6c3c386..6b94240 100644
--- a/include/opkele/verify_op.h
+++ b/include/opkele/verify_op.h
@@ -1,16 +1,26 @@
 #ifndef __OPKELE_VERIFY_OP_H
 #define __OPKELE_VERIFY_OP_H
 
 #include <opkele/basic_op.h>
 
 namespace opkele {
 
+    /**
+     * The OP implementation that does discovery verification on RP
+     */
     class verify_op : public basic_OP {
         public:
 
+        /**
+         * In addition to basic_OP::verify_return_to() functionality this
+         * implementation does the discovery on RP to see if return_to matches
+         * the realm
+         * @throw bad_return_to in case we fail to discover corresponding
+         * service endpoint
+         */
         void verify_return_to();
     };
 
 }
 
 #endif /* __OPKELE_VERIFY_OP_H */