further doxygenation of basic_OP, extension_t and verify_OP

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

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,34 +1,37 @@
 #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
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
@@ -23,39 +23,47 @@ namespace opkele {
 	     * 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 */