Some more docs and cleanup

adambeynon · adambeynon · commit b1fb9b6e76ea · 2014-12-06T21:10:00.000Z
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,10 @@
 # EDGE
 
+*   Add `Browser::Window` class, and make `::Window` an instance of it.
+
+*   Make `Document` include `Browser::DocumentMethods` which is a simple
+    module to define custom methods for `Document`.
+
 *   Cleanup HTTP implementation.
 
 *   `Element#[]` and `Element#attr` now return `nil` for empty attributes,
@@ -15,7 +20,7 @@
 *   Add Promise support to `HTTP` get/post/put/delete methods. Also remove
     `HTTP#callback` and `#errback` methods.
 
-# 0.2.0 - December 3, 2014
+# 0.2.0 - March 12, 2013
 
 *   Add `Document.body` and `Document.head` shortcut to element instances.
 
diff --git a/opal/opal-jquery/document.rb b/opal/opal-jquery/document.rb
@@ -1,33 +1,93 @@
 require 'opal-jquery/constants'
 require 'opal-jquery/element'
 
-# {Document} is an instance of {Element} that wraps the `document` object as
-# a simple jQuery object.
-Document = Element.find(`document`)
-
-class << Document
-  `var $ = #{JQUERY_SELECTOR.to_n}` # cache $ for SPEED
+module Browser
+  # {Document} includes these methods to extend {Element}.
+  #
+  # Generally, you will want to use the {::Document} top level instance of
+  # {Element}.
+  #
+  # ## Usage
+  #
+  # A useful method on {Document} is the {#ready?} method, which can be used to
+  # run a block once the document is ready. This is equivalent to passing a
+  # function to the `jQuery` constructor.
+  #
+  #     Document.ready? do
+  #       puts "Page is ready to use!"
+  #     end
+  #
+  # Just like jQuery, multiple blocks may be passed to {#ready?}.
+  #
+  # ### Document head and body elements
+  #
+  # Every document has atleast two elements: a `head` and `body`. For
+  # convenience, these are both exposed as {#head} and {#body} respectively,
+  # and are just instances of {Element}.
+  #
+  #     puts Document.head
+  #     puts Document.body
+  #
+  #     # => #<Element: [<head>]>
+  #     # => #<Element: [<body>]>
+  #
+  # ### Events
+  #
+  # {Document} instances also have {#on}, {#off} and {#trigger} methods for
+  # handling events. These all just delegate to their respective methods on
+  # {Element}, using `document` as the context.
+  #
+  #     Document.on :click do |evt|
+  #       puts "someone clicked somewhere in the document"
+  #     end
+  #
+  module DocumentMethods
+    `var $ = #{JQUERY_SELECTOR.to_n}` # cache $ for SPEED
 
-  def ready?(&block)
-    `$(#{ block })` if block
-  end
+    # Register a block to run once the document/page is ready.
+    #
+    # @example
+    #   Document.ready? do
+    #     puts "ready to go"
+    #   end
+    #
+    def ready?(&block)
+      `$(#{block})` if block_given?
+    end
 
-  def title
-    `document.title`
-  end
+    # Returns document title.
+    #
+    # @return [String]
+    def title
+      `document.title`
+    end
 
-  def title=(title)
-    `document.title = #{title}`
-  end
+    # Set document title.
+    #
+    # @param title [String]
+    def title=(title)
+      `document.title = title`
+    end
 
-  def head
-    Element.find(`document.head`)
-  end
+    # {Element} instance wrapping `document.head`.
+    #
+    # @return [Element]
+    def head
+      Element.find `document.head`
+    end
 
-  def body
-    Element.find(`document.body`)
+    # {Element} instance wrapping `document.body`.
+    #
+    # @return [Element]
+    def body
+      Element.find `document.body`
+    end
   end
 end
 
+# Top level {Document} instance wrapping `window.document`.
+Document = Element.find(`document`)
+Document.send(:extend, Browser::DocumentMethods)
+
 # TODO: this will be removed soon (here for compatibility)
 $document = Document
diff --git a/opal/opal-jquery/element.rb b/opal/opal-jquery/element.rb
@@ -305,6 +305,8 @@ def self.expose(*methods)
   # @!method []=(attr, value)
   #
   # Set the given attribute `attr` on each element in this collection.
+  #
+  # @see http://api.jquery.com/attr/
   alias_native :[]=, :attr
 
   # @!method add_class(class_name)
diff --git a/opal/opal-jquery/event.rb b/opal/opal-jquery/event.rb
@@ -1,13 +1,87 @@
 require 'opal-jquery/constants'
 
-# Wraps native jQuery event objects.
+# {Event} wraps native jQuery events into a ruby api. Instances of events
+# can be accessed by {#to_n}.
+#
+# {Event} instances should not be created directly, as they are usually
+# created by one of the dom event handlers in {Element}.
+#
+#     element.on :click do |event|
+#       puts event
+#     end
+#
+#     # => #<Event:0x0000000>
+#
+# ## Usage
+#
+# {Event} exposes a slightly different API than jQuery, as {Event} tries to
+# add some more ruby flavour to the object.
+#
+# ### Accessing element triggering event
+#
+# Unlike jQuery, the context of an event handler is not set to the triggering
+# element. Instead, the element triggering the event can be accessed from the
+# {Event} instance.
+#
+# #### Current Target
+#
+# To access the current element in the bubbling phase, {#element} or
+# {#current_target} can be used which is the same as `currentTarget` or `this`
+# from jQuery.
+#
+#     element.on :click do |event|
+#       puts "element clicked: #{event.element}
+#     end
+#
+#     # => "element clicked: #<Element: [<div>]>
+#
+# #### Target
+#
+# The {#target} of an event is the actual dom element that triggered the event,
+# and this will be the same element through all phases of event bubbling. This
+# is the same as the `event.target` jQuery property.
+#
+#     element.on :click do |event|
+#       puts "actual element: #{event.target}"
+#     end
+#
+#     # => "actual element: #<Element: [<div>]>
+#
+# ### Controlling Event Bubbling
+#
+# Propagation and default behaviour can be controlled on events using {#prevent}
+# and {#stop}, which will prevent the browser default and stop event propagation
+# respectively.
+#
+#     element.on :click do |event|
+#       event.prevent   # prevent browser default
+#       event.stop      # stop event propagation
+#     end
+#
+# If you want to trigger both methods, which is usually the case, then {#kill}
+# can be used as a shorthand.
+#
+#     element.on :click do |event|
+#       event.kill
+#       puts event.prevented?
+#       puts event.stopped?
+#     end
+#
+#     # => true
+#     # => true
+#
 class Event
   `var $ = #{JQUERY_SELECTOR.to_n}` # cache $ for SPEED
 
+  # @private
+  # @param native [JSObject] native jquery/javascript event
   def initialize(native)
     @native = native
   end
 
+  # Returns native javascript event created by jQuery.
+  #
+  # @return [JSObject]
   def to_n
     @native
   end
@@ -20,32 +94,47 @@ def type
     `#@native.type`
   end
 
-  ##
-  # Element
-
-  def current_target
+  # Returns the current element in the bubbling cycle of the event. This is
+  # not the same as the actual dom event that triggered the event, but is
+  # usually the context element the event was registered with, or the target
+  # of the css selector used in newer event styles.
+  #
+  # @return [Element]
+  def element
     `$(#@native.currentTarget)`
   end
 
+  alias current_target element
+
+  # Returns the actual element that triggered the dom event.
+  #
+  # @return [Element]
   def target
     `$(#@native.target)`
   end
 
-  ##
-  # Propagation
-
+  # Returns `true` if this event has had its default browser behaviour
+  # prevented, `false` otherwise.
+  #
+  # @return [Boolean]
   def prevented?
     `#@native.isDefaultPrevented()`
   end
 
+  # Prevent this event from triggering its default browser behaviour.
   def prevent
     `#@native.preventDefault()`
   end
 
+  # Returns `true` if the propagation/bubbling of this event has been stopped,
+  # `false` otherwise.
+  #
+  # @return [Boolean]
   def stopped?
     `#@native.isPropagationStopped()`
   end
 
+  # Stop further propagaion of this event.
   def stop
     `#@native.stopPropagation()`
   end
@@ -55,18 +144,14 @@ def stop_immediate
   end
 
   # Stops propagation and prevents default action.
+  #
+  # @see {#prevent}
+  # @see {#stop}
   def kill
     stop
     prevent
   end
 
-  # to be removed?
-  alias default_prevented? prevented?
-  alias prevent_default prevent
-  alias propagation_stopped? stopped?
-  alias stop_propagation stop
-  alias stop_immediate_propagation stop_immediate
-
   ##
   # Keyboard/Mouse/Touch
 
@@ -97,4 +182,12 @@ def key_code
   def which
     `#@native.which`
   end
+
+  # @deprecated These will be removed soon
+  alias default_prevented? prevented?
+  alias prevent_default prevent
+  alias propagation_stopped? stopped?
+  alias stop_propagation stop
+  alias stop_immediate_propagation stop_immediate
+
 end
diff --git a/opal/opal-jquery/local_storage.rb b/opal/opal-jquery/local_storage.rb
@@ -14,29 +14,56 @@ module Browser
   #     LocalStorage['bar'] # => nil
   #
   # @see LocalStorage
+  #
   class LocalStorage
     def initialize(storage)
       @storage = storage
     end
 
+    # Set a value in storage.
+    #
+    # Values stored in {LocalStorage} will be stored as strings. To store any
+    # other type of object, you will need to convert them to a string first,
+    # and then convert them back from {#[]}. For this reason it is recommended
+    # to only store {JSON} based objects in storage, so they can be easily
+    # converted back and forth.
+    #
+    # @param key [String] string key
+    # @param value [String, #to_s] string or explicitly converted object
     def []=(key, value)
       %x{
         #@storage.setItem(key, value);
         return value;
       }
     end
 
+    # Retrieve an object from {LocalStorage}.
+    #
+    # Only string values can be stored, so any object will be returned as a
+    # string. You will need to handle any conversion back into a normal
+    # object. {JSON.parse} could be used, for example, to parse back into
+    # arrays or hashes.
+    #
+    # If a key is not present in the storage, then `nil` will be returned.
+    #
+    # @param key [String] key to lookup
+    # @return [String, nil]
     def [](key)
       %x{
         var value = #@storage.getItem(key);
         return value == null ? nil : value;
       }
     end
 
+    # Removes a specific `key` from storage. If the key does not exist then
+    # there is no side effect.
+    #
+    # @param key [String] key to remove
     def delete(key)
       `#@storage.removeItem(key)`
     end
 
+    # Remove all key/values from storage
     def clear
       `#@storage.clear()`
     end
diff --git a/opal/opal-jquery/window.rb b/opal/opal-jquery/window.rb

Original file line number	Diff line number	Diff line change
`@@ -305,6 +305,8 @@ def self.expose(*methods)`
`305`	`305`	`# @!method []=(attr, value)`
`306`	`306`	`#`
`307`	`307`	# Set the given attribute `attr` on each element in this collection.
	`308`	`+ #`
	`309`	`+ # @see http://api.jquery.com/attr/`
`308`	`310`	`alias_native :[]=, :attr`
`309`	`311`
`310`	`312`	`# @!method add_class(class_name)`