From ad067583516d0a32e4ad996acbdac0357f0af994 Mon Sep 17 00:00:00 2001
From: Andreas Waidler <arandes@programmers.at>
Date: Sun, 26 Sep 2010 11:50:33 +0200
Subject: [PATCH] Improved doc and syntax.

---
 include/libsex/Exception.hxx | 16 ++++++++++++++--
 include/libsex/utility.hxx   |  5 ++++-
 include/libsex/utility.ixx   |  3 ++-
 libsex.pc.in                 |  2 +-
 4 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/include/libsex/Exception.hxx b/include/libsex/Exception.hxx
index d693a39..316ca5c 100644
--- a/include/libsex/Exception.hxx
+++ b/include/libsex/Exception.hxx
@@ -14,7 +14,7 @@ namespace libsex {
  * The supplied character array must be terminated by a
  * nullbyte. It will be copied into an internal array
  * (stored on the stack) that is @ref LENGTH chars long,
- * until the nullbyte is reached or the internal array is
+ * until a nullbyte is reached or the internal array is
  * full.
  *
  * It is possible create chained exceptions. Since we have
@@ -26,7 +26,19 @@ namespace libsex {
  * 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.
+ * and previous exceptions are ignored. Instances that have
+ * already been copied on the heap will be deleted
+ * automatically when the latest exception (on the stack)
+ * gets out of scope (RAII).
+ *
+ * Constructors that accept instances of std::string as
+ * error messages have been left out. These strings utilize
+ * the heap which may result in above mentioned "double
+ * fault". Thus, accepting std::string is likely to turn
+ * out to be a pitfall. However, std::string responds to
+ * the message @c c_str by providing a pointer to the
+ * underlying character stringm so this design decision
+ * does not create any problems.
  *
  * @note For OO error handling you should subclass this
  *       class for every type of error. Inheriting by hand
diff --git a/include/libsex/utility.hxx b/include/libsex/utility.hxx
index 5a9da60..59b8c96 100644
--- a/include/libsex/utility.hxx
+++ b/include/libsex/utility.hxx
@@ -50,7 +50,10 @@ bool format(
  * @return Instance of T.
  */
 template <typename T>
-T formatted(const char* const file, unsigned short line, ...) throw();
+T formatted(
+	const char* const file,
+	unsigned short line,
+	...) throw();
 
 }; // End of namespace.
 
diff --git a/include/libsex/utility.ixx b/include/libsex/utility.ixx
index e67a48b..489d8cc 100644
--- a/include/libsex/utility.ixx
+++ b/include/libsex/utility.ixx
@@ -3,7 +3,8 @@
 namespace libsex {
 
 template <typename T>
-T formatted(const char* const file,
+T formatted(
+	const char* const file,
 	unsigned short line,
 	...) throw()
 {
diff --git a/libsex.pc.in b/libsex.pc.in
index 0c089b3..7df9db2 100644
--- a/libsex.pc.in
+++ b/libsex.pc.in
@@ -4,7 +4,7 @@ libdir=@libdir@
 includedir=@includedir@
 
 Name: @PACKAGE@
-Description: LIBrary for Simple (and powerful) EXception handling.
+Description: Library providing a simple exception framework for C++.
 Version: @VERSION@
 Libs: -L${libdir} -lsex
 Cflags: -I${includedir}
-- 
2.11.4.GIT