[seed] [docs] Significantly updated exception documentation

[Tim Horton <hortont src gnome org>]

commit 8b599c999131de68d7fe26f09aa68e2e4a56efd6
Author: Tim Horton <hortont424 gmail com>
Date:   Thu Jul 9 00:57:41 2009 -0400

    [docs] Significantly updated exception documentation

 doc/reference/tmpl/seed-exception.sgml |    1 +
 libseed/seed-exceptions.c              |   23 +++++++++++++++++++++--
 2 files changed, 22 insertions(+), 2 deletions(-)
---
diff --git a/doc/reference/tmpl/seed-exception.sgml b/doc/reference/tmpl/seed-exception.sgml
index 24ba385..c8462aa 100644
--- a/doc/reference/tmpl/seed-exception.sgml
+++ b/doc/reference/tmpl/seed-exception.sgml
@@ -19,6 +19,7 @@ Throwing and catching exceptions
 </itemizedlist>
 </para>
 </note>
+
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
diff --git a/libseed/seed-exceptions.c b/libseed/seed-exceptions.c
index 998bef4..1b451f5 100644
--- a/libseed/seed-exceptions.c
+++ b/libseed/seed-exceptions.c
@@ -115,6 +115,10 @@ seed_make_exception_from_gerror (JSContextRef ctx,
  * @ctx: A #SeedContext.
  * @exception: A reference to a #SeedException.
  *
+ * Retrieves the name of the given exception; this could be one of the
+ * predefined exception names given above, or your own name, which should
+ * be a single CamelCase word, preferably ending in something like "Error".
+ *
  * Return value: A #gchar* representing the name of @exception.
  *
  */
@@ -135,6 +139,11 @@ seed_exception_get_name (JSContextRef ctx, JSValueRef e)
  * @ctx: A #SeedContext.
  * @exception: A reference to a #SeedException.
  *
+ * Retrieves the message of the given exception; this should be a
+ * human-readable string describing the exception enough that a developer
+ * could utilize the message in order to determine where to look to debug
+ * the problem.
+ *
  * Return value: A #gchar* representing the detailed message of @exception.
  *
  */
@@ -155,6 +164,9 @@ seed_exception_get_message (JSContextRef ctx, JSValueRef e)
  * @ctx: A #SeedContext.
  * @exception: A reference to a #SeedException.
  *
+ * Retrieves the line number the given exception was thrown from; keep in mind
+ * that exceptions created from C have an undefined line number.
+ *
  * Return value: A #guint representing the line number from which @exception
  *               was thrown.
  *
@@ -175,6 +187,9 @@ seed_exception_get_line (JSContextRef ctx, JSValueRef e)
  * @ctx: A #SeedContext.
  * @exception: A reference to a #SeedException.
  *
+ * Retrieves the file name the given exception was thrown from; keep in mind
+ * that exceptions created from C have an undefined file name.
+ *
  * Return value: A #gchar* representing the name of the file from which
  *               @exception was thrown.
  *
@@ -195,8 +210,12 @@ seed_exception_get_file (JSContextRef ctx, JSValueRef e)
  * @ctx: A #SeedContext.
  * @exception: A reference to a #SeedException.
  *
- * Return value: A #gchar* representing the name, detailed message, line number,
- *               and file name of @exception.
+ * Properly formats the name, detailed message, line number, and file name of
+ * the given extension. This provides a consistent format for printed
+ * exceptions, to reduce confusion. Please use it if you're exposing exception
+ * data to the outside world.
+ *
+ * Return value: A #gchar* representing the @exception.
  *
  */
 gchar *