From 3660beb798c16800c6fc3ad153acff99790e16ff Mon Sep 17 00:00:00 2001
From: Gordon Sim <gsim@apache.org>
Date: Mon, 5 Sep 2011 19:00:23 +0000
Subject: NO-JIRA: Additional doxygen comments for exceptions

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk/qpid@1165391 13f79535-47bb-0310-9956-ffa450edef68
---
 cpp/include/qpid/messaging/Session.h    | 45 +++++++++++++++++++++-
 cpp/include/qpid/messaging/exceptions.h | 68 +++++++++++++++++++++++++++------
 2 files changed, 100 insertions(+), 13 deletions(-)

(limited to 'cpp/include')

diff --git a/cpp/include/qpid/messaging/Session.h b/cpp/include/qpid/messaging/Session.h
index 428f8aa491..e8d6efb35d 100644
--- a/cpp/include/qpid/messaging/Session.h
+++ b/cpp/include/qpid/messaging/Session.h
@@ -62,6 +62,12 @@ class QPID_MESSAGING_CLASS_EXTERN Session : public qpid::messaging::Handle<Sessi
      */
     QPID_MESSAGING_EXTERN void close();
 
+    /**
+     * Commits the sessions transaction.
+     *
+     * @exception TransactionAborted if the original session is lost
+     * forcing an automatic rollback.
+     */
     QPID_MESSAGING_EXTERN void commit();
     QPID_MESSAGING_EXTERN void rollback();
 
@@ -139,25 +145,51 @@ class QPID_MESSAGING_CLASS_EXTERN Session : public qpid::messaging::Handle<Sessi
     /**
      * Create a new sender through which messages can be sent to the
      * specified address.
+     *
+     * @exception ResolutionError if there is an error in resolving
+     * the address
      */
     QPID_MESSAGING_EXTERN Sender createSender(const Address& address);
+    /**
+     * Create a new sender through which messages can be sent to the
+     * specified address.
+     *
+     * @exception ResolutionError if there is an error in resolving
+     * the address
+     *
+     * @exception MalformedAddress if the syntax of address is not
+     * valid
+     */
     QPID_MESSAGING_EXTERN Sender createSender(const std::string& address);
 
     /**
      * Create a new receiver through which messages can be received
      * from the specified address.
+     *
+     * @exception ResolutionError if there is an error in resolving
+     * the address
      */
     QPID_MESSAGING_EXTERN Receiver createReceiver(const Address& address);
+    /**
+     * Create a new receiver through which messages can be received
+     * from the specified address.
+     *
+     * @exception ResolutionError if there is an error in resolving
+     * the address
+     *
+     * @exception MalformedAddress if the syntax of address is not
+     * valid
+     */
     QPID_MESSAGING_EXTERN Receiver createReceiver(const std::string& address);
 
     /**
      * Returns the sender with the specified name.
-     *@exception KeyError if there is none for that name.
+     * @exception KeyError if there is none for that name.
      */
     QPID_MESSAGING_EXTERN Sender getSender(const std::string& name) const;
     /**
      * Returns the receiver with the specified name.
-     *@exception KeyError if there is none for that name.
+     * @exception KeyError if there is none for that name.
      */
     QPID_MESSAGING_EXTERN Receiver getReceiver(const std::string& name) const;
     /**
@@ -166,7 +198,16 @@ class QPID_MESSAGING_CLASS_EXTERN Session : public qpid::messaging::Handle<Sessi
      */
     QPID_MESSAGING_EXTERN Connection getConnection() const;
 
+    /**
+     * @returns true if the session has been rendered invalid by some
+     * exception, false if it is valid for use.
+     */
     QPID_MESSAGING_EXTERN bool hasError();
+    /**
+     * If the session has been rendered invalid by some exception,
+     * this method will result in that exception being thrown on
+     * calling this method.
+     */
     QPID_MESSAGING_EXTERN void checkError();
 
 #ifndef SWIG
diff --git a/cpp/include/qpid/messaging/exceptions.h b/cpp/include/qpid/messaging/exceptions.h
index 07d1dc414b..31e2488d91 100644
--- a/cpp/include/qpid/messaging/exceptions.h
+++ b/cpp/include/qpid/messaging/exceptions.h
@@ -10,9 +10,9 @@
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
- * 
+ *
  *   http://www.apache.org/licenses/LICENSE-2.0
- * 
+ *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
@@ -29,23 +29,36 @@
 namespace qpid {
 namespace messaging {
 
-/** \ingroup messaging 
+/** \ingroup messaging
  */
 
-struct QPID_MESSAGING_CLASS_EXTERN MessagingException : public qpid::types::Exception 
+/**
+ * This is the base class for all messaging related exceptions thrown
+ * by this API.
+ */
+struct QPID_MESSAGING_CLASS_EXTERN MessagingException : public qpid::types::Exception
 {
     QPID_MESSAGING_EXTERN MessagingException(const std::string& msg);
     QPID_MESSAGING_EXTERN virtual ~MessagingException() throw();
-    
+
     qpid::types::Variant::Map detail;
     //TODO: override what() to include detail if present
 };
 
-struct QPID_MESSAGING_CLASS_EXTERN InvalidOptionString : public MessagingException 
+/**
+ * Thrown when the syntax of the option string used to configure a
+ * connection in not valid
+ */
+struct QPID_MESSAGING_CLASS_EXTERN InvalidOptionString : public MessagingException
 {
     QPID_MESSAGING_EXTERN InvalidOptionString(const std::string& msg);
 };
 
+/**
+ * Thrown to indicate a failed lookup of some local object. For
+ * example when attempting to retrieve a session, sender or receiver
+ * by name.
+ */
 struct QPID_MESSAGING_CLASS_EXTERN KeyError : public MessagingException
 {
     QPID_MESSAGING_EXTERN KeyError(const std::string&);
@@ -65,25 +78,33 @@ struct QPID_MESSAGING_CLASS_EXTERN AddressError : public LinkError
  * Thrown when a syntactically correct address cannot be resolved or
  * used.
  */
-struct QPID_MESSAGING_CLASS_EXTERN ResolutionError : public AddressError 
+struct QPID_MESSAGING_CLASS_EXTERN ResolutionError : public AddressError
 {
     QPID_MESSAGING_EXTERN ResolutionError(const std::string& msg);
 };
 
-struct QPID_MESSAGING_CLASS_EXTERN AssertionFailed : public ResolutionError 
+/**
+ * Thrown when creating a sender or receiver for an address for which
+ * some asserted property of the node is not matched.
+ */
+struct QPID_MESSAGING_CLASS_EXTERN AssertionFailed : public ResolutionError
 {
     QPID_MESSAGING_EXTERN AssertionFailed(const std::string& msg);
 };
 
-struct QPID_MESSAGING_CLASS_EXTERN NotFound : public ResolutionError 
+/**
+ * Thrown on attempts to create a sender or receiver to a non-existent
+ * node.
+ */
+struct QPID_MESSAGING_CLASS_EXTERN NotFound : public ResolutionError
 {
     QPID_MESSAGING_EXTERN NotFound(const std::string& msg);
 };
 
 /**
- * Thrown when an address string with inalid sytanx is used.
+ * Thrown when an address string with invalid syntax is used.
  */
-struct QPID_MESSAGING_CLASS_EXTERN MalformedAddress : public AddressError 
+struct QPID_MESSAGING_CLASS_EXTERN MalformedAddress : public AddressError
 {
     QPID_MESSAGING_EXTERN MalformedAddress(const std::string& msg);
 };
@@ -98,6 +119,11 @@ struct QPID_MESSAGING_CLASS_EXTERN FetchError : public ReceiverError
     QPID_MESSAGING_EXTERN FetchError(const std::string&);
 };
 
+/**
+ * Thrown by Receiver::fetch(), Receiver::get() and
+ * Session::nextReceiver() to indicate that there no message was
+ * available before the timeout specified.
+ */
 struct QPID_MESSAGING_CLASS_EXTERN NoMessageAvailable : public FetchError
 {
     QPID_MESSAGING_EXTERN NoMessageAvailable();
@@ -113,6 +139,11 @@ struct QPID_MESSAGING_CLASS_EXTERN SendError : public SenderError
     QPID_MESSAGING_EXTERN SendError(const std::string&);
 };
 
+/**
+ * Thrown to indicate that the sender attempted to send a message that
+ * would result in the target node on the peer exceeding a
+ * preconfigured capacity.
+ */
 struct QPID_MESSAGING_CLASS_EXTERN TargetCapacityExceeded : public SendError
 {
     QPID_MESSAGING_EXTERN TargetCapacityExceeded(const std::string&);
@@ -128,11 +159,19 @@ struct QPID_MESSAGING_CLASS_EXTERN TransactionError : public SessionError
     QPID_MESSAGING_EXTERN TransactionError(const std::string&);
 };
 
+/**
+ * Thrown on Session::commit() if reconnection results in the
+ * transaction being automatically aborted.
+ */
 struct QPID_MESSAGING_CLASS_EXTERN TransactionAborted : public TransactionError
 {
     QPID_MESSAGING_EXTERN TransactionAborted(const std::string&);
 };
 
+/**
+ * Thrown to indicate that the application attempted to do something
+ * for which it was not authorised by its peer.
+ */
 struct QPID_MESSAGING_CLASS_EXTERN UnauthorizedAccess : public SessionError
 {
     QPID_MESSAGING_EXTERN UnauthorizedAccess(const std::string&);
@@ -143,6 +182,13 @@ struct QPID_MESSAGING_CLASS_EXTERN ConnectionError : public MessagingException
     QPID_MESSAGING_EXTERN ConnectionError(const std::string&);
 };
 
+/**
+ * Thrown to indicate loss of underlying connection. When
+ * auto-reconnect is used this will be caught by the library and used
+ * to trigger reconnection attempts. If reconnection fails (according
+ * to whatever settings have been configured), then an instnace of
+ * this class will be thrown to signal that.
+ */
 struct QPID_MESSAGING_CLASS_EXTERN TransportFailure : public MessagingException
 {
     QPID_MESSAGING_EXTERN TransportFailure(const std::string&);
-- 
cgit v1.2.1