immediate: cleanup and add documentation

meh · meh · commit 634dbf9b637c · 2014-01-21T01:16:06.000+01:00
diff --git a/opal/browser/compatibility/immediate.rb b/opal/browser/compatibility/immediate.rb
@@ -51,7 +51,10 @@ def prevent
       `window.msClearImmediate(#@id)`
     end
   elsif C.post_message?
+    # @private
     @@tasks  = {}
+
+    # @private
     @@prefix = "opal.browser.immediate.#{rand(1_000_000)}."
 
     $window.on :message do |e|
diff --git a/opal/browser/immediate.rb b/opal/browser/immediate.rb
@@ -1,26 +1,54 @@
 require 'promise'
 
-require 'browser/compatibility/immediate'
-
 module Browser
 
-# FIXME: drop the method_defined? checks when require order is fixed
+# Class to easily create and dispatch an immediate call.
+#
+# Immediate calls are deferred function calls that happen as soon as they can
+# be scheduled.
+#
+# Compatibility
+# -------------
+# The compatibility layer will try various implementations in the following
+# order.
+#
+# + [setImmediate](https://developer.mozilla.org/en-US/docs/Web/API/Window.setImmediate)
+# + [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window.postMessage)
+# + [readystatechange](https://developer.mozilla.org/en-US/docs/Web/Reference/Events/readystatechange)
+# + [setTimeout](https://developer.mozilla.org/en/docs/Web/API/window.setTimeout)
+#
+# The order has been chosen from best to worst for both performance and
+# preemptiveness.
+#
+# @todo drop the method_defined? checks when require order is fixed
 class Immediate
+  # Create an immediate for the given function which will be called with the
+  # arguments and block.
+  #
+  # @param func [Proc] the function to call
+  # @param args [Array] the arguments to call it with
   def initialize(func, args, &block)
     @aborted   = false
     @function  = func
     @arguments = args
     @block     = block
   end
 
+  # Dispatch the immediate.
+  #
+  # @abstract
   def dispatch
     raise NotImplementedError
   end unless method_defined? :dispatch
 
+  # Prevent the immediate from being called once scheduled.
+  #
+  # @abstract
   def prevent
     raise NotImplementedError
   end unless method_defined? :prevent
 
+  # Abort the immediate.
   def abort
     return if aborted?
 
@@ -30,6 +58,7 @@ def abort
     self
   end
 
+  # Check if the immediate has been aborted.
   def aborted?
     @aborted
   end
@@ -38,13 +67,16 @@ def aborted?
 end
 
 class Proc
-  # Defer the function to be called as soon as possible.
+  # (see Immediate.new)
   def defer(*args, &block)
     Browser::Immediate.new(self, args, &block).tap(&:dispatch)
   end
 end
 
 class Promise
+  # Create a promise which will be resolved with the result of the immediate.
+  #
+  # @param args [Array] the arguments the block will be called with
   def self.defer(*args, &block)
     new.tap {|promise|
       proc {
@@ -57,3 +89,5 @@ def self.defer(*args, &block)
     }
   end
 end
+
+require 'browser/compatibility/immediate'
diff --git a/spec/immediate_spec.rb b/spec/immediate_spec.rb
@@ -1,12 +1,14 @@
 require 'spec_helper'
 require 'browser/immediate'
 
-describe Browser::Immediate do
-  async 'defers a proc' do
-    proc {|a|
-      run_async {
-        a.should == 42
-      }
-    }.defer(42)
+describe Proc do
+  describe '#defer' do
+    async 'works properly' do
+      proc {|a|
+        run_async {
+          a.should == 42
+        }
+      }.defer(42)
+    end
   end
 end
