From be674573cf159f2217b7bd6d5613530432277c2f Mon Sep 17 00:00:00 2001
From: Andreas Waidler <arandes@programmers.at>
Date: Sat, 25 Sep 2010 20:15:00 +0200
Subject: [PATCH] Improved doc.

---
 include/libsex/Exception.hxx | 59 ++++++++++++++++++++++++++++++++------------
 include/libsex/macros.hxx    |  4 +--
 include/libsex/utility.hxx   |  6 ++---
 include/libsex/utility.ixx   |  2 +-
 4 files changed, 49 insertions(+), 22 deletions(-)

diff --git a/include/libsex/Exception.hxx b/include/libsex/Exception.hxx
index e4c9b28..d693a39 100644
--- a/include/libsex/Exception.hxx
+++ b/include/libsex/Exception.hxx
@@ -1,5 +1,5 @@
-#ifndef EXCEPTION_HXX
-#define EXCEPTION_HXX
+#ifndef LIBSEX_EXCEPTION_HXX
+#define LIBSEX_EXCEPTION_HXX
 
 #include <exception> // std::exception
 #include <stdexcept> // std::bad_alloc
@@ -17,27 +17,54 @@ namespace libsex {
  * until the nullbyte is reached or the internal array is
  * full.
  *
- * For OO error handling you should subclass this class for
- * every type of error. Inheriting by hand is tedious, you
- * usally don't want to do this. There are some efficient
- * macros in @file create.hxx.
+ * It is possible create chained exceptions. Since we have
+ * to assume that all exceptions are created on the stack,
+ * the previous exception will be copied to the heap and
+ * the current exception stores a pointer to this copy
+ * (singly linked list).
  *
- * @note The previous exceptions, if any, will be copied
- *       by calling clone() which may in turn throw
- *       std::bad_alloc. In that case, a notice is appended
- *       to this message (as long as the array contains
- *       free fields) and the exception is swallowed.
+ * Hence, it is possible that, while having a chain of
+ * exceptions "bubbling up", a std::bad_alloc is thrown. In
+ * this case, a notice is appended and both std::bad_alloc
+ * and previous exceptions are ignored.
+ *
+ * @note For OO error handling you should subclass this
+ *       class for every type of error. Inheriting by hand
+ *       is tedious, you usally don't want to do this.
+ *       There are some efficient macros in @file
+ *       macros.hxx.
  */
 class Exception : public std::exception
 {
 public:
-	/// Max payload in the internal c-string.
+	/// Max payload of the internal character string.
 	static const unsigned short LENGTH = 500;
 
-	/// Creates an Exception.
+	/**
+	 * Creates an exception.
+	 *
+	 * The specified message is copied into an internal
+	 * buffer of @ref LENGTH + 1 (nullbyte) characters
+	 * length.
+	 */
 	Exception(const char* const message) throw();
 
-	/// Creates an Ex. that references a previous one.
+	/**
+	 * Creates a chained exception.
+	 *
+	 * Both the error message and the previous
+	 * exception are copied. While @a message is copied
+	 * into an internal buffer, clone() is send to @a
+	 * previous which in turn dynamically creates a
+	 * shallow copy of itsself on the heap and returns
+	 * a pointer to it.
+	 *
+	 * Hence, it is possible that clone() may throw
+	 * std::bad_alloc. In that case, a notice is
+	 * appended to this message (as long as the
+	 * internal buffer contains free fields) and the
+	 * instance of std::bad_alloc is swallowed.
+	 */
 	Exception(
 		const char* const message,
 		const Exception& previous) throw();
@@ -72,14 +99,14 @@ public:
 	 */
 	virtual const Exception* clone() const throw(std::bad_alloc);
 
-	/// @return a pointer to the internal cstring.
+	/// Returns a pointer to the internal character string.
 	virtual const char* what() const throw();
 
 private:
 	/**
 	 * Copy of message passed to constructor.
 	 *
-	 * Length is Exception::LENGTH plus nullbyte.
+	 * Length is @ref Exception::LENGTH plus nullbyte.
 	 */
 	char _message[LENGTH + 1];
 
diff --git a/include/libsex/macros.hxx b/include/libsex/macros.hxx
index b5b995e..270c2f8 100644
--- a/include/libsex/macros.hxx
+++ b/include/libsex/macros.hxx
@@ -1,5 +1,5 @@
-#ifndef MACROS_HXX
-#define MACROS_HXX
+#ifndef LIBSEX_MACROS_HXX
+#define LIBSEX_MACROS_HXX
 
 /// Macro for declaring exception classes (.hxx).
 #define LIBSEX_DECLARE(parent, name) \
diff --git a/include/libsex/utility.hxx b/include/libsex/utility.hxx
index b9d0415..5a9da60 100644
--- a/include/libsex/utility.hxx
+++ b/include/libsex/utility.hxx
@@ -1,5 +1,5 @@
-#ifndef UTILITY_HXX
-#define UTILITY_HXX
+#ifndef LIBSEX_UTILITY_HXX
+#define LIBSEX_UTILITY_HXX
 
 #include <cstdarg> // variadic argument fun
 #include <cstdio>  // size_t
@@ -52,7 +52,7 @@ bool format(
 template <typename T>
 T formatted(const char* const file, unsigned short line, ...) throw();
 
-}; // namespace
+}; // End of namespace.
 
 #include "utility.ixx"
 
diff --git a/include/libsex/utility.ixx b/include/libsex/utility.ixx
index c3ebeb6..e67a48b 100644
--- a/include/libsex/utility.ixx
+++ b/include/libsex/utility.ixx
@@ -23,4 +23,4 @@ T formatted(const char* const file,
 	return T(buf);
 }
 
-}; // namespace
+}; // End of namespace.
-- 
2.11.4.GIT