syntax.js.coffee in upjs-rails-0.12.5

- old
+ new

@@ -153,11 +153,11 @@
           $(this).something();
         });
       });
 
   
-  @method up.compiler
+  @function up.compiler
   @param {String} selector
     The selector to match.
   @param {Boolean} [options.batch=false]
     If set to `true` and a fragment insertion contains multiple
     elements matching the selector, `compiler` is only called once
@@ -202,11 +202,11 @@
         if compiler.batch
           applyCompiler(compiler, $matches, $matches.get())
         else
           $matches.each -> applyCompiler(compiler, $(this), this)
 
-  destroy = ($fragment) ->
+  runDestroyers = ($fragment) ->
     u.findWithSelf($fragment, ".#{DESTROYABLE_CLASS}").each ->
       $element = $(this)
       destroyer = $element.data(DESTROYER_KEY)
       destroyer()
 
@@ -218,33 +218,30 @@
 
   The API of this method is likely to change in the future, so
   we can support getting or setting individual keys.
 
   @protected
-  @method up.syntax.data
+  @function up.syntax.data
   @param {String|Element|jQuery} elementOrSelector
-  ###
+  @return
+    The JSON-decoded value of the `up-data` attribute.
 
+    Returns an empty object (`{}`) if the element has no (or an empty) `up-data` attribute.
   ###
-  Looks for an `up-data` attribute on the given element, then parses
-  its value as JSON and returns the JSON object.
 
+  ###
   If an element annotated with [`up-data`] is inserted into the DOM,
   Up will parse the JSON and pass the resulting object to any matching
   [`up.compiler`](/up.syntax.compiler) handlers.
 
   Similarly, when an event is triggered on an element annotated with
   [`up-data`], the parsed object will be passed to any matching
   [`up.on`](/up.on) handlers.
 
-  @ujs
-  @method [up-data]
-  @param {JSON} [up-data]
-  @return
-    The JSON-decoded value of the `up-data` attribute.
-
-    Returns an empty object (`{}`) if the element has no (or an empty) `up-data` attribute.
+  @selector [up-data]
+  @param {JSON} up-data
+    A serialized JSON string
   ###
   data = (elementOrSelector) ->
     $element = $(elementOrSelector)
     json = $element.attr('up-data')
     if u.isString(json) && u.trim(json) != ''
@@ -282,20 +279,38 @@
 
       // Add an element with naked jQuery, without going through Upjs:
       $element = $('<div>...</div>').appendTo(document.body);
       up.hello($element);
 
-  @method up.hello
+  This function emits the [`up:fragment:inserted`](/up:fragment:inserted)
+  event.
+
+  @function up.hello
   @param {String|Element|jQuery} selectorOrElement
   ###
   hello = (selectorOrElement) ->
     $element = $(selectorOrElement)
     up.emit('up:fragment:inserted', $element: $element)
     $element
 
+  ###*
+  When a page fragment has been [inserted or updated](/up.replace),
+  this event is [emitted](/up.emit) on the fragment.
+
+  \#\#\#\# Example
+
+      up.on('up:fragment:inserted', function(event, $fragment) {
+        console.log("Looks like we have a new %o!", $fragment);
+      });
+
+  @event up:fragment:inserted
+  @param {jQuery} event.$element
+    The fragment that has been inserted or updated.
+  ###
+
   up.on 'ready', (-> hello(document.body))
   up.on 'up:fragment:inserted', (event) -> compile(event.$element)
-  up.on 'up:fragment:destroy', (event) -> destroy(event.$element)
+  up.on 'up:fragment:destroy', (event) -> runDestroyers(event.$element)
   up.on 'up:framework:boot', snapshot
   up.on 'up:framework:reset', reset
 
   compiler: compiler
   hello: hello