Document the exceptions

Doxyfile

@@ -5,3 +5,4 @@ FILE_PATTERNS = *.h *.m
 HTML_OUTPUT = .
 GENERATE_LATEX = NO
 HIDE_UNDOC_CLASSES = YES
+PREDEFINED = OF_HAVE_PROPERTIES

src/XMPPExceptions.h

@@ -25,22 +25,47 @@
 @class XMPPConnection;
 @class XMPPAuthenticator;
 
+/**
+ * \brief A base class for XMPP related exceptions
+ */
 @interface XMPPException: OFException
 {
 	XMPPConnection *connection;
 }
 
 #ifdef OF_HAVE_PROPERTIES
+/// The connection the exception relates to
 @property (readonly, nonatomic) XMPPConnection *connection;
 #endif
 
+/**
+ * Creates a new XMPPException
+ *
+ * \param class_ The class of the object which caused the exception
+ * \param connection The connection that received the data responsible
+ *	  for this exception
+ * \return A new XMPPException
+ */
 + exceptionWithClass: (Class)class_
-	  connection: (XMPPConnection*)conn;
+	  connection: (XMPPConnection*)connection;
+
+/**
+ * Initializes an already allocated XMPPException
+ *
+ * \param class_ The class of the object which caused the exception
+ * \param connection The connection that received the data responsible
+ *	  for this exception
+ * \return An initialized XMPPException
+ */
 - initWithClass: (Class)class_
-     connection: (XMPPConnection*)conn;
+     connection: (XMPPConnection*)connection;
+
 - (XMPPConnection*)connection;
 @end
 
+/**
+ * \brief An exception indicating a stream error was received
+ */
 @interface XMPPStreamErrorException: XMPPException
 {
 	OFString *condition;
@@ -48,22 +73,48 @@
 }
 
 #ifdef OF_HAVE_PROPERTIES
+/// The defined error condition specified by the stream error
 @property (readonly, nonatomic) OFString *condition;
+/// The descriptive free-form text specified by the stream error
 @property (readonly, nonatomic) OFString *reason;
 #endif
 
+/**
+ * Creates a new XMPPStreamErrorException
+ *
+ * \param class_ The class of the object which caused the exception
+ * \param connection The connection that received the stream error
+ * \param condition The defined error condition specified by the stream error
+ * \param reason The descriptive free-form text specified by the stream error
+ * \return A new XMPPStreamErrorException
+ */
 + exceptionWithClass: (Class)class_
-	  connection: (XMPPConnection*)conn
+	  connection: (XMPPConnection*)connection
-     condition: (OFString*)condition_
+	   condition: (OFString*)condition
-	reason: (OFString*)reason_;
+	      reason: (OFString*)reason;
+
+/**
+ * Initializes an already allocated XMPPStreamErrorException
+ *
+ * \param class_ The class of the object which caused the exception
+ * \param connection The connection that received the stream error
+ * \param condition The defined error condition specified by the stream error
+ * \param reason The descriptive free-form text specified by the stream error
+ * \return An initialized XMPPStreamErrorException
+ */
 - initWithClass: (Class)class_
-     connection: (XMPPConnection*)conn
+     connection: (XMPPConnection*)connection
-      condition: (OFString*)condition_
+      condition: (OFString*)condition
-	 reason: (OFString*)reason_;
+	 reason: (OFString*)reason;
+
 - (OFString*)condition;
 - (OFString*)reason;
 @end
 
+/**
+ * \brief An exception indicating a stringprep profile
+ *	  did not apply to a string
+ */
 @interface XMPPStringPrepFailedException: XMPPException
 {
 	OFString *profile;
@@ -71,21 +122,47 @@
 }
 
 #ifdef OF_HAVE_PROPERTIES
-@property (readonly, nonatomic) OFString *profile, *string;
+/// The name of the stringprep profile that did not apply
+@property (readonly, nonatomic) OFString *profile;
+/// The string that failed the stringprep profile
+@property (readonly, nonatomic) OFString *string;
 #endif
 
+/**
+ * Creates a new XMPPStringPrepFailedException
+ *
+ * \param class_ The class of the object which caused the exception
+ * \param connection The connection the string relates to
+ * \param profile The name of the stringprep profile that did not apply
+ * \param string The string that failed the stringprep profile
+ * \return A new XMPPStringPrepFailedException
+ */
 + exceptionWithClass: (Class)class_
-	  connection: (XMPPConnection*)conn
+	  connection: (XMPPConnection*)connection
 	     profile: (OFString*)profile
 	      string: (OFString*)string;
+
+/**
+ *  Initializes an already allocated XMPPStringPrepFailedException
+ *
+ * \param class_ The class of the object which caused the exception
+ * \param connection The connection the string relates to
+ * \param profile The name of the stringprep profile that did not apply
+ * \param string The string that failed the stringprep profile
+ * \return An initialized XMPPStringPrepFailedException
+ */
 - initWithClass: (Class)class_
-     connection: (XMPPConnection*)conn
+     connection: (XMPPConnection*)connection
 	profile: (OFString*)profile
 	 string: (OFString*)string;
+
 - (OFString*)profile;
 - (OFString*)string;
 @end
 
+/**
+ * \brief An exception indicating IDNA translation of a string failed
+ */
 @interface XMPPIDNATranslationFailedException: XMPPException
 {
 	OFString *operation;
@@ -93,35 +170,80 @@
 }
 
 #ifdef OF_HAVE_PROPERTIES
-@property (readonly, nonatomic) OFString *operation, *string;
+/// The IDNA translation operation which failed
+@property (readonly, nonatomic) OFString *operation;
+/// The string that could not be translated
+@property (readonly, nonatomic) OFString *string;
 #endif
 
+/**
+ * Creates a new XMPPIDNATranslationFailedException
+ *
+ * \param class_ The class of the object which caused the exception
+ * \param connection The connection the string relates to
+ * \param operation The name of the stringprep profile that did not apply
+ * \param string The string that could not be translated
+ * \return A new XMPPIDNATranslationFailedException
+ */
 + exceptionWithClass: (Class)class_
-	  connection: (XMPPConnection*)conn
+	  connection: (XMPPConnection*)connection
 	   operation: (OFString*)operation
 	      string: (OFString*)string;
+
+/**
+ * Initializes an already allocated XMPPIDNATranslationFailedException
+ *
+ * \param class_ The class of the object which caused the exception
+ * \param connection The connection the string relates to
+ * \param operation The name of the stringprep profile that did not apply
+ * \param string The string that could not be translated
+ * \return An initialized XMPPIDNATranslationFailedException
+ */
 - initWithClass: (Class)class_
-     connection: (XMPPConnection*)conn
+     connection: (XMPPConnection*)connection
       operation: (OFString*)operation
 	 string: (OFString*)string;
+
 - (OFString*)operation;
 - (OFString*)string;
 @end
 
+/**
+ * \brief An exception indicating authentication failed
+ */
 @interface XMPPAuthFailedException: XMPPException
 {
 	OFString *reason;
 }
 
 #ifdef OF_HAVE_PROPERTIES
+/// The reason the authentication failed
 @property (readonly, nonatomic) OFString *reason;
 #endif
 
+/**
+ * Creates a new XMPPAuthFailedException
+ *
+ * \param class_ The class of the object which caused the exception
+ * \param connection The connection that could not be authenticated
+ * \param reason The reason the authentication failed
+ * \return A new XMPPAuthFailedException
+ */
 + exceptionWithClass: (Class)class_
-	  connection: (XMPPConnection*)conn
+	  connection: (XMPPConnection*)connection
-	      reason: (OFString*)reason_;
+	      reason: (OFString*)reason;
+
+/**
+ * Initializes an already allocated XMPPAuthFailedException
+ *
+ * \param class_ The class of the object which caused the exception
+ * \param connection The connection that could not be authenticated
+ * \param reason The reason the authentication failed
+ * \return An initialized XMPPAuthFailedException
+ */
 - initWithClass: (Class)class_
-     connection: (XMPPConnection*)conn
+     connection: (XMPPConnection*)connection
-	 reason: (OFString*)reason_;
+	 reason: (OFString*)reason;
+
 - (OFString*)reason;
 @end