From 67311e07fd92a4f444b8701245b7fbcb58663879 Mon Sep 17 00:00:00 2001
From: tjcrowder <tj@crowdersoftware.com>
Date: Fri, 21 Aug 2009 16:35:42 +0100
Subject: [PATCH] doc: Moved scope warning from Ajax.Updater to
 String#evalScripts and left cross link. [#38 state:resolved]

---
 src/ajax/updater.js | 32 ++++++--------------------------
 src/lang/string.js  | 39 +++++++++++++++++++++++++++++++++++----
 2 files changed, 41 insertions(+), 30 deletions(-)

diff --git a/src/ajax/updater.js b/src/ajax/updater.js
index d1a2bc8..6979dfa 100644
--- a/src/ajax/updater.js
+++ b/src/ajax/updater.js
@@ -37,33 +37,13 @@
  *    `top`, `bottom`, `before`, or `after` &mdash; and _inserts_ the contents of the
  *    response in the manner described by [[Element#insert]].
  *
- *  <h4>About `evalScripts` and defining functions</h4>
+ *  <h4>More About `evalScripts`</h4>
  *
- *  If you use `evalScripts: true`, any `<script>` block will be evaluated.
- *  This **does not** mean it will be evaluated in the global scope. In other
- *  words:
- *
- *  * The evaluation scope will be that of Prototype's internal processing
- *    function. Anything in your script declared with the `var` keyword will be
- *    discarded momentarily after evaluation, and will be invisible to any
- *    other scope.
- *  * If any `<script>` blocks inside Ajax responses _define functions_, they
- *    will need to be assigned to properties of the `window` object &mdash; _not_
- *    declared with the `function` keyword.
- *
- *  For example, this won't work:
- *
- *      // This kind of script won't work if processed by Ajax.Updater:
- *      function coolFunc() {
- *        // Amazing stuff!
- *      }
- *
- *  Instead, use the following syntax:
- *
- *      // This kind of script WILL work if processed by Ajax.Updater:
- *      coolFunc = function() {
- *        // Amazing stuff!
- *      }
+ *  If you use `evalScripts: true`, any _inline_ `<script>` block will be evaluated.
+ *  This **does not** mean it will be evaluated in the global scope; it won't, and that
+ *  has important ramifications for your `var` and `function` statements.  Also note
+ *  that only inline `<script>` blocks are supported; external scripts are ignored.
+ *  See [[String#evalScripts]] for the details.
  *
  *  <h4>Single container, or success/failure split?</h4>
  *
diff --git a/src/lang/string.js b/src/lang/string.js
index 3327546..265be1b 100644
--- a/src/lang/string.js
+++ b/src/lang/string.js
@@ -157,8 +157,39 @@ Object.extend(String.prototype, (function() {
   /**
    *  String#evalScripts() -> Array
    *
-   *  Evaluates the content of any script block present in the string.
+   *  Evaluates the content of any inline `<script>` block present in the string.
    *  Returns an array containing the value returned by each script.
+   *  `<script>`  blocks referencing external files will be treated as though
+   *  they were empty (the result for that position in the array will be `undefined`);
+   *  external files are _not_ loaded and processed by `evalScripts`.
+   *
+   *  <h4>About `evalScripts`, `var`s, and defining functions</h4>
+   *
+   *  `evalScripts` evaluates script blocks, but this **does not** mean they are
+   *  evaluated in the global scope. They aren't, they're evaluated in the scope of
+   *  the `evalScripts` method. This has important ramifications for your scripts:
+   *
+   *  * Anything in your script declared with the `var` keyword will be
+   *    discarded momentarily after evaluation, and will be invisible to any
+   *    other scope.
+   *  * If any `<script>` blocks _define functions_, they will need to be assigned to
+   *    properties of the `window` object.
+   *
+   *  For example, this won't work:
+   *
+   *      // This kind of script won't work if processed by evalScripts:
+   *      function coolFunc() {
+   *        // Amazing stuff!
+   *      }
+   *
+   *  Instead, use the following syntax:
+   *
+   *      // This kind of script WILL work if processed by evalScripts:
+   *      window.coolFunc = function() {
+   *        // Amazing stuff!
+   *      }
+   *
+   *  (You can leave off the `window.` part of that, but it's bad form.)
   **/
   function evalScripts() {
     return this.extractScripts().map(function(script) { return eval(script) });
@@ -250,12 +281,12 @@ Object.extend(String.prototype, (function() {
    *
    *  Converts a string separated by dashes into a camelCase equivalent.
    *  For instance, 'foo-bar' would be converted to 'fooBar'.
-   *  
+   *
    *  <h4>Examples</h4>
-   *  
+   *
    *      'background-color'.camelize();
    *      // -> 'backgroundColor'
-   *      
+   *
    *      '-moz-binding'.camelize();
    *      // -> 'MozBinding'
   **/