[seed] [docs] Update SeedScript/evaluation docs

[Tim Horton <hortont src gnome org>]

commit a3b64d47ed29af92f5cb0d4afe34962f67df6a24
Author: Tim Horton <hortont svn gnome org>
Date:   Sun Jul 12 15:21:26 2009 -0400

    [docs] Update SeedScript/evaluation docs

 doc/reference/tmpl/seed-eval.sgml |   34 +++++++++++++++++++++++++++++++++-
 libseed/seed-api.c                |   10 ++++++++--
 2 files changed, 41 insertions(+), 3 deletions(-)
---
diff --git a/doc/reference/tmpl/seed-eval.sgml b/doc/reference/tmpl/seed-eval.sgml
index 31aa236..7d0e0d8 100644
--- a/doc/reference/tmpl/seed-eval.sgml
+++ b/doc/reference/tmpl/seed-eval.sgml
@@ -6,9 +6,41 @@ Creating and interpreting scripts
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-Long description
+Seed relies on WebKit's JavaScriptCore interpreter to actually evaluate snippets of JavaScript; however, it provides a handful of useful wrapper functions to quickly create and evaluate scripts. seed_make_script() and seed_evaluate() are the workhorse functions; these allow you to control every detail of the created script and its evaluation environment (including customizing the "this" object during evaluation, and setting a starting line number and filename from which the script originates). seed_simple_evaluate() provides an interface to execute a string of JavaScript without previously creating a #SeedScript, and, while requiring less supporting code, is less flexible.
 </para>
 
+<example>
+<title>Create and evaluate a string of JavaScript with seed_make_script()</title>
+<programlisting>
+SeedEngine * eng;
+&nbsp;
+...
+&nbsp;    
+SeedScript * script;
+/* Create a simple #SeedScript */
+script = seed_make_script(eng->context, "print('Hello, world!')", NULL, 0);
+&nbsp;
+/* Evaluate the #SeedScript in the default context */
+seed_evaluate(eng->context, script, 0);
+&nbsp;
+...
+</programlisting>
+</example>
+
+<example>
+<title>Create and evaluate a string of JavaScript with seed_simple_evaluate()</title>
+<programlisting>
+SeedEngine * eng;
+&nbsp;
+...
+&nbsp;
+/* Evaluate a simple JavaScript snippet in the default context */
+seed_simple_evaluate(eng->context, "print('Hello, world!')", NULL);
+&nbsp;
+...
+</programlisting>
+</example>
+
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
diff --git a/libseed/seed-api.c b/libseed/seed-api.c
index 37e0723..9fae65f 100644
--- a/libseed/seed-api.c
+++ b/libseed/seed-api.c
@@ -203,6 +203,9 @@ seed_object_call (JSContextRef ctx,
  * Creates a new #SeedScript instance with @js as the contents, then
  * checks for proper syntax.
  *
+ * Note: seed_make_script() does not handle the shebang line, and will return a
+ *       parse error if one is included in @js.
+ *
  * Return value: The newly created #SeedScript.
  *
  */
@@ -292,7 +295,8 @@ seed_evaluate (JSContextRef ctx,
  * @source: A string representing the JavaScript to evaluate.
  * @exception: A #SeedException pointer to store an exception in.
  *
- * Evaluates a string of JavaScript.
+ * Evaluates a string of JavaScript in @ctx; if an exception
+ * is raised in the context of the script, it will be placed in @exception.
  *
  * Return value: The #SeedValue returned by evaluating the script.
  *
@@ -315,7 +319,9 @@ seed_simple_evaluate (JSContextRef ctx,
  * seed_script_exception:
  * @s: A #SeedScript.
  *
- * Return value: A #JSValueRef representing the exception of @s.
+ * Retrieves the exception (if any) raised during the evaluation of @s.
+ *
+ * Return value: A #SeedException representing the exception of @s.
  *
  */
 JSValueRef