documentation for PendingCall

include/dbus-c++/pendingcall.h

@@ -49,18 +49,74 @@ public:
 
 	PendingCall& operator = ( const PendingCall& );
 
+  /*!
+   * \brief Checks whether the pending call has received a reply yet, or not.
+   *
+   * \return true If a reply has been received.
+   */
 	bool completed();
 	
+  /*!
+   * \brief Cancels the pending call, such that any reply or error received will 
+   *        just be ignored.
+   *
+   * Drops the dbus library's internal reference to the DBusPendingCall so will 
+   * free the call if nobody else is holding a reference. However you usually 
+   * get a reference from Connection::send_async() so probably your app 
+   * owns a ref also.
+   *
+   * Note that canceling a pending call will not simulate a timed-out call; if a 
+   * call times out, then a timeout error reply is received. If you cancel the 
+   * call, no reply is received unless the the reply was already received before 
+   * you canceled.
+   */
 	void cancel();
 
+  /*!
+   * \brief Block until the pending call is completed.
+   *
+   * The blocking is as with Connection::send_blocking(); it
+   * does not enter the main loop or process other messages, it simply waits for
+   * the reply in question.
+   *
+   * If the pending call is already completed, this function returns immediately.
+   */
 	void block();
 
+  /*!
+   * \brief Stores a pointer on a PendingCall, along with an optional function to 
+   *        be used for freeing the data when the data is set again, or when the
+   *        pending call is finalized.
+   *
+   * The slot is allocated automatic.
+   *
+   * \param data The data to store.
+   */
 	void data( void* );
 
+  /*!
+   * \brief Retrieves data previously set with dbus_pending_call_set_data().
+   *
+   * The slot must still be allocated (must not have been freed).
+   *
+   * \return The data, or NULL if not found.
+   */
 	void* data();
 
+  /*!
+   * \return The data slot.
+   */
 	Slot<void, PendingCall&>& slot();
 
+  /*!
+   * \brief Gets the reply
+   *
+   * Ownership of the reply message passes to the caller. This function can only 
+   * be called once per pending call, since the reply message is tranferred to 
+   * the caller.
+   *
+   * \return The reply Message.
+	 */
    Message steal_reply();
 
 private: