From 67087f4374ddca69c4d3d9303e85795f060f50a2 Mon Sep 17 00:00:00 2001
From: Kevin Smith <git@kismith.co.uk>
Date: Wed, 25 Jan 2012 10:14:56 +0000
Subject: Adding documentation to GenericRequest


diff --git a/Swiften/Queries/GenericRequest.h b/Swiften/Queries/GenericRequest.h
index 9fd934f..b9cc6fc 100644
--- a/Swiften/Queries/GenericRequest.h
+++ b/Swiften/Queries/GenericRequest.h
@@ -11,9 +11,25 @@
 #include <Swiften/Queries/Request.h>
 
 namespace Swift {
+	/**
+	 * GenericRequest is used for managing the sending of, and handling of replies to, iq stanzas that do not have their own Request types.
+	 *
+	 * To create an iq stanza, call a constructor with the type of the iq that needs to be sent (either Set or Get), addressing information (clients should use the constructor that doesn't specify a sender), the payload that should be sent in the iq, and the IQRouter for the connection, obtained through the Client or CoreClient object.
+	 * 
+	 * Having created a GenericRequest, connect to the onResponse signal to be told when a response (either a result or an error) has been received by Swiften.
+	 *
+	 * To send the iq, then call send() - onResponse will be called when a reply is received.
+	 */
 	template<typename PAYLOAD_TYPE>
 	class GenericRequest : public Request {
 		public:
+			/**
+			 * Create a request suitable for client use.
+			 * @param type Iq type - Get or Set.
+			 * @param receiver JID to send request to.
+			 * @param payload Payload to send in stanza.
+			 * @param router IQRouter instance for current connection.
+			 */
 			GenericRequest(
 					IQ::Type type, 
 					const JID& receiver, 
@@ -22,6 +38,14 @@ namespace Swift {
 						Request(type, receiver, payload, router) {
 			}
 
+			/**
+			 * Create a request suitable for component or server use. As a client, use the other constructor instead.
+			 * @param type Iq type - Get or Set.
+			 * @param sender JID to use in "from" of stanza.
+			 * @param receiver JID to send request to.
+			 * @param payload Payload to send in stanza.
+			 * @param router IQRouter instance for current connection.
+			 */
 			GenericRequest(
 					IQ::Type type,
 					const JID& sender,
@@ -31,6 +55,9 @@ namespace Swift {
 						Request(type, sender, receiver, payload, router) {
 			}
 
+			/**
+			 * Internal method, do not use.
+			 */
 			virtual void handleResponse(boost::shared_ptr<Payload> payload, ErrorPayload::ref error) {
 				onResponse(boost::dynamic_pointer_cast<PAYLOAD_TYPE>(payload), error);
 			}
@@ -41,6 +68,9 @@ namespace Swift {
 			}
 
 		public:
+			/**
+			 * Signal emitted when a reply to the iq has been received. Contains a payload if one was present, and an error if one was present.
+			 */
 			boost::signal<void (boost::shared_ptr<PAYLOAD_TYPE>, ErrorPayload::ref)> onResponse;
 	};
 }
-- 
cgit v0.10.2-6-g49f6