watir-classic 3.3.0 → 3.4.0

data/lib/watir-classic/element_collection.rb

@@ -1,11 +1,12 @@
 module Watir
-  # this class is the super class for the iterator classes (buttons, links, spans etc
-  # it would normally only be accessed by the iterator methods (spans, links etc) of IE
+  # This class is the super class for the iterator classes (buttons, links, spans etc).
+  # It would normally only be accessed by the iterator methods (spans, links etc) of {Container}.
   class ElementCollection
     include Enumerable
 
     # Super class for all the iterator classes
-    #   * container - an instance of an IE object
+    # @param [Element] container container element instance.
+    # @param [Hash] specifiers locators for elements.
     def initialize(container, specifiers)
       if specifiers[:index]
         raise Exception::MissingWayOfFindingObjectException,
@@ -17,6 +18,7 @@ module Watir
       @page_container = container.page_container
     end
 
+    # @return [Fixnum] count of elements in this collection.
     def length
       count = 0
       each {|element| count += 1 }
@@ -25,28 +27,36 @@ module Watir
 
     alias_method :size, :length
 
-    # iterate through each of the elements in the collection in turn
+    # Iterate through each of the elements in the collection in turn.
+    # @yieldparam [Element] element element instance.
     def each
       @container.locator_for(TaggedElementLocator, @specifiers, element_class).each {|element| yield element}
     end
 
-    # allows access to a specific item in the collection
+    # Access a specific item in the collection.
+    #
+    # @note {Element} will be always returned even if the index is out of
+    #   bounds. Use {Element#exists?} to verify if the element actually exists.
+    # @param [Fixnum] n n-th element to retrieve.
+    # @return [Element] element with specified index from this collection.
     def [](n)
-      number = n - Watir::IE.base_index
-      offset = Watir::IE.zero_based_indexing ? (length - 1) : length
       non_existing_element = element_class.new(@container, @specifiers.merge(:index => n))
       def non_existing_element.locate; nil end
-      iterator_object(number) || non_existing_element
+      iterator_object(n) || non_existing_element
     end
 
+    # @return [Element] first element from this collection.
     def first
       iterator_object(0)
     end
 
+    # @return [Element] last element from this collection.
     def last
       iterator_object(length - 1)
     end
 
+    # @return [String] String representation of each element in this collection
+    #   separated by line-feed.
     def to_s
       map { |e| e.to_s }.join("\n")
     end
@@ -71,12 +81,14 @@ module Watir
 
   end
 
+  # This class represents table elements collection.
   class TableElementCollection < ElementCollection
     def initialize(container, specifiers, ole_collection=nil)
       super container, specifiers
       @ole_collection = ole_collection
     end
 
+    # @see ElementCollection#each
     def each
       if @ole_collection
         elements = []
@@ -90,17 +102,23 @@ module Watir
     end
   end
 
+  # This class represents table row elements collection.
   class TableRowCollection < TableElementCollection; end
 
+  # This class represents table cell elements collection.
   class TableCellCollection < TableElementCollection; end
 
+  # This class represents input elements collection.  
   class InputElementCollection < ElementCollection
+    # @see ElementCollection#each
     def each
       @container.locator_for(InputElementLocator, @specifiers, element_class).each {|element| yield element}
     end    
   end
 
+  # This class represents general elements collection.
   class HTMLElementCollection < ElementCollection
+    # @see ElementCollection#each
     def each
       @container.locator_for(TaggedElementLocator, @specifiers, Element).each { |element| yield element }
     end

data/lib/watir-classic/element_extensions.rb

@@ -1,14 +1,13 @@
 # encoding: utf-8
 
 module Watir
-# This assumes that Element#visible? is defined
+  # This module adds some helper methods for asynchronous testing.
   module ElementExtensions
 
-    #
-    # Wraps a {Celerity,Watir}::Element so that any subsequent method calls are
+    # Wraps an {Element} so that any subsequent method calls are
     # put on hold until the element is present on the page.
     #
-
+    # @private
     class WhenPresentDecorator
       def initialize(element, timeout)
         @element = element
@@ -28,26 +27,25 @@ module Watir
 
     end
 
-    #
-    # Returns true if the element exists and is visible on the page
-    #
-
+    # @return [Boolean] true when element exists and is visible, false otherwise.
     def present?
       exists? && visible? rescue false
     end
 
+    # Waits until the element is present before calling its methods.
     #
-    # Waits until the element is present.
+    # @example
+    #   browser.button(:id, 'foo').when_present.click
     #
-    # Optional argument:
+    # @example
+    #   browser.div(:id, 'bar').when_present { |div| ... }
     #
-    #   timeout   -  seconds to wait before timing out (default: 60)
+    # @example
+    #   browser.p(:id, 'baz').when_present(60).text
     #
-    #     browser.button(:id, 'foo').when_present.click
-    #     browser.div(:id, 'bar').when_present { |div| ... }
-    #     browser.p(:id, 'baz').when_present(60).text
-    #
-
+    # @param [Fixnum] timeout seconds to wait before timing out.
+    # @raise [Watir::Wait::TimeoutError] will be raised when element is not
+    #   present within specified timeout.
     def when_present(timeout = 60)
       if block_given?
         Watir::Wait.until(timeout) { self.present? }
@@ -57,10 +55,18 @@ module Watir
       end
     end
 
+    # Wait until element is present before continuing.
+    #
+    # @raise [Watir::Wait::TimeoutError] will be raised when element is not
+    #   present within specified timeout.
     def wait_until_present(timeout = 60)
       Watir::Wait.until(timeout) { self.present? }
     end
 
+    # Wait while element is present before continuing.
+    #
+    # @raise [Watir::Wait::TimeoutError] will be raised when element is still present
+    #   after specified timeout.
     def wait_while_present(timeout = 60)
       Watir::Wait.while(timeout) { self.present? }
     end

data/lib/watir-classic/exceptions.rb

@@ -3,11 +3,11 @@ module Watir
 
     # Root class for all Watir Exceptions
     class WatirException < RuntimeError  
-			def initialize(message="")
-				super(message)
-			end
+      def initialize(message="")
+        super(message)
+      end
     end
-    
+
     # This exception is raised if an attempt is made to access an object that doesn't exist
     class UnknownObjectException < WatirException; end
     # This exception is raised if an attempt is made to access an object that is in a disabled state

data/lib/watir-classic/form.rb

@@ -1,24 +1,33 @@
 module Watir
 
+  # Returned by {Container#form}.
   class Form < Element
+
+    attr_ole :action
+
     def initialize(container, specifiers)
       super
       copy_test_config container
     end
 
-    attr_ole :action
-
+    # @return [String] form name attribute value. Will be empty string if does not
+    #   exist.
+    # @macro exists
     def name
       assert_exists
       name = ole_object.getAttributeNode('name')
       name ? name.value : ''
     end
 
+    # @return [String] form method attribute value.
+    # @macro exists
     def form_method
       assert_exists
       ole_object.invoke('method')
     end
-
+    
+    # @param [Object] arg when argument is nil, {#form_method} will be called.
+    #   Otherwise Ruby's {Kernel#method} will be called.
     def method(arg = nil)
       if arg.nil?
         form_method
@@ -27,68 +36,62 @@ module Watir
       end
     end    
 
-    def locate
-      @o = @container.locator_for(FormLocator, @specifiers, self.class).locate
-    end
-
-    # Submit the data -- equivalent to pressing Enter or Return to submit a form.
+    # Submit the form.
+    # @note Will not submit the form if its onSubmit JavaScript callback
+    #   returns false.
+    # @macro exists
     def submit 
       assert_exists
       @o.submit(0) if dispatch_event "onSubmit"
       @container.wait
     end
-    
+   
+    # Flash the element the specified number of times for troubleshooting purposes.
+    # @param [Fixnum] number number of times to flash the element.
+    # @macro exists
+    def flash(number=10)
+      assert_exists
+      @original_element_colors = {}
+      number.times do
+        set_highlight
+        sleep 0.05
+        clear_highlight
+        sleep 0.05
+      end
+    end
+
+    # @private
+    def locate
+      @o = @container.locator_for(FormLocator, @specifiers, self.class).locate
+    end
+
+    # @private
     def __ole_inner_elements
       assert_exists
       @o.elements
     end
 
-    # This method is responsible for setting and clearing the colored highlighting on the specified form.
-    # use :set  to set the highlight
-    #   :clear  to clear the highlight
-    def highlight(set_or_clear, element, count)
-      if set_or_clear == :set
-        begin
+    private
+
+    # This method is responsible for setting the colored highlighting on the specified form.
+    def set_highlight
+      @o.elements.each do |element|
+        perform_highlight do
           original_color = element.style.backgroundColor
-          original_color = "" if original_color==nil
-          element.style.backgroundColor = activeObjectHighLightColor
-        rescue => e
-          puts e
-          puts e.backtrace.join("\n")
-          original_color = ""
-        end
-        @original_styles[count] = original_color
-      else
-        begin
-          element.style.backgroundColor = @original_styles[ count]
-        rescue => e
-          puts e
-          # we could be here for a number of reasons...
-        ensure
+          element.style.backgroundColor = active_object_highlight_color        
+          @original_element_colors[element] = original_color
         end
       end
     end
-    private :highlight
-    
-    # causes the object to flash. Normally used in IRB when creating scripts
-    # Default is 10
-    def flash number=10
-      assert_exists
-      @original_styles = {}
-      number.times do
-        count = 0
-        @o.elements.each do |element|
-          highlight(:set, element, count)
-          count += 1
-        end
-        sleep 0.05
-        count = 0
-        @o.elements.each do |element|
-          highlight(:clear, element, count)
-          count += 1
+
+    # This method is responsible for clearing the colored highlighting on the specified form.
+    def clear_highlight
+      @original_element_colors.each_pair do |element, color|
+        perform_highlight do
+          element.style.backgroundColor = color
         end
-        sleep 0.05
       end
+      @original_element_colors.clear
     end
     
   end # class Form

data/lib/watir-classic/frame.rb

@@ -1,7 +1,9 @@
 module Watir
+  # Returned by the {Container#frame}.
   class Frame < Element
     include PageContainer
-    attr_accessor :document
+
+    attr_writer :document
 
     attr_ole :name
     attr_ole :src
@@ -11,7 +13,26 @@ module Watir
       copy_test_config container
     end
     
+    # @return [WIN32OLE] frame's document object.
+    # @raise [FrameAccessDeniedException] when IE security settings won't allow
+    #   to access the frame
+    # @macro exists
+    def document
+      assert_exists
+      if @document
+        @document
+      else
+        raise FrameAccessDeniedException, "IE will not allow access to this frame for security reasons. You can work around this with ie.goto(frame.src)"
+      end
+    end
+
+    # @private
+    def attach_command
+      @container.page_container.attach_command + ".frame(:unique_number => #{unique_number})"
+    end
+
     # Find the frame denoted by specifiers in the container and return its ole_object
+    # @private
     def locate
       frame, document = @container.locator_for(FrameLocator, @specifiers, self.class).locate
       if frame && document
@@ -26,22 +47,10 @@ module Watir
       end
     end
 
+    # @private
     def __ole_inner_elements
       document.body.all
     end
 
-    def document
-      assert_exists
-      if @document
-        @document
-      else
-        raise FrameAccessDeniedException, "IE will not allow access to this frame for security reasons. You can work around this with ie.goto(frame.src)"
-      end
-    end
-
-    def attach_command
-      @container.page_container.attach_command + ".frame(#{@specifiers.inspect})".gsub('"','\'')
-    end
-
   end
 end

data/lib/watir-classic/ie-class.rb

@@ -1,352 +1,332 @@
 module Watir
+  # Main browser class.
   class IE
     include WaitHelper
     include Exception
     include Container
     include PageContainer
 
-    # Maximum number of seconds to wait when attaching to a window
-    @@attach_timeout = 2.0 # default value
-    def self.attach_timeout
-      @@attach_timeout
-    end
-    def self.attach_timeout=(timeout)
-      @@attach_timeout = timeout
-    end
+    class << self
+      # Maximum number of seconds to wait when attaching to a window
+      attr_writer :attach_timeout
 
-    # Return the options used when creating new instances of IE.
-    # BUG: this interface invites misunderstanding/misuse such as IE.options[:speed] = :zippy]
-    def self.options
-      {:speed => self.speed, :visible => self.visible, :attach_timeout => self.attach_timeout, :zero_based_indexing => self.zero_based_indexing}
-    end
-    # set values for options used when creating new instances of IE.
-    def self.set_options options
-      options.each do |name, value|
-        send "#{name}=", value
+      def attach_timeout
+        @attach_timeout ||= 2
       end
-    end
-    # The globals $FAST_SPEED and $HIDE_IE are checked both at initialization
-    # and later, because they
-    # might be set after initialization. Setting them beforehand (e.g. from
-    # the command line) will affect the class, otherwise it is only a temporary
-    # effect
-    @@speed = $FAST_SPEED ? :fast : :slow
-    def self.speed
-      return :fast if $FAST_SPEED
-      @@speed
-    end
-    def self.speed= x
-      $FAST_SPEED = nil
-      @@speed = x
-    end
-    @@visible = $HIDE_IE ? false : true
-    def self.visible
-      return false if $HIDE_IE
-      @@visible
-    end
-    def self.visible= x
-      $HIDE_IE = nil
-      @@visible = x
-    end
 
-    @@zero_based_indexing = true
-    def self.zero_based_indexing= enabled
-      @@zero_based_indexing = enabled
-    end
+      # Return the options used when creating new instances of IE.
+      # BUG: this interface invites misunderstanding/misuse such as IE.options[:speed] = :zippy]
+      def options
+        {:speed => self.speed, :visible => self.visible, :attach_timeout => self.attach_timeout}
+      end
 
-    def self.zero_based_indexing
-      @@zero_based_indexing
-    end
+      # set values for options used when creating new instances of IE.
+      def set_options options
+        options.each do |name, value|
+          send "#{name}=", value
+        end
+      end
 
-    def self.base_index
-      self.zero_based_indexing ? 0 : 1
-    end  
+      # The speed in which browser will type keys etc. Possible values are
+      # :slow (default), :fast and :zippy.
+      attr_writer :speed
 
-    # Used internally to determine when IE has finished loading a page
-    READYSTATES = {:complete => 4}
+      def speed
+        @speed ||= :slow
+      end
 
-    # The default color for highlighting objects as they are accessed.
-    HIGHLIGHT_COLOR = 'yellow'
+      # Set browser window to visible or hidden. Defaults to true.
+      attr_writer :visible
 
-    # The time, in seconds, it took for the new page to load after executing the
-    # the last command
-    attr_reader :down_load_time
+      def visible
+        @visible ||= true
+      end
 
-    # the OLE Internet Explorer object
-    attr_accessor :ie
+      # Create a new IE window.
+      def new_window
+        ie = new true
+        ie._new_window_init
+        ie
+      end
 
-    # this contains the list of unique urls that have been visited
-    attr_reader :url_list
+      # Create a new IE, starting at the specified url.
+      # @param [String] url url to navigate to.
+      def start(url=nil)
+        start_window url
+      end
 
-    # Create a new IE window. Works just like IE.new in Watir 1.4.
-    def self.new_window
-      ie = new true
-      ie._new_window_init
-      ie
-    end
+      # Create a new IE window, starting at the specified url.
+      # @param [String] url url to navigate to.
+      def start_window(url=nil)
+        ie = new_window
+        ie.goto url if url
+        ie
+      end
 
-    # Create an IE browser.
-    def initialize suppress_new_window=nil
-      _new_window_init unless suppress_new_window
-    end
+      # Create a new IE window in a new process. 
+      # @note This method will not work when
+      #   Watir/Ruby is run under a service (instead of a user).
+      def new_process
+        ie = new true
+        ie._new_process_init
+        ie
+      end
 
-    def _new_window_init
-      create_browser_window
-      initialize_options
-      goto 'about:blank' # this avoids numerous problems caused by lack of a document
-    end
+      # Create a new IE window in a new process, starting at the specified URL. 
+      # @param [String] url url to navigate to.
+      def start_process(url=nil)
+        ie = new_process
+        ie.goto url if url
+        ie
+      end
 
-    # Create a new IE Window, starting at the specified url.
-    # If no url is given, start empty.
-    def self.start url=nil
-      start_window url
-    end
+      # Attach to an existing IE {Browser}.
+      #
+      # @example Attach with full title:
+      #   Watir::Browser.attach(:title, "Full title of IE")
+      #
+      # @example Attach with part of the title using {Regexp}:
+      #   Watir::Browser.attach(:title, /part of the title of IE/)
+      #
+      # @example Attach with part of the url:
+      #   Watir::Browser.attach(:url, /google/)
+      #
+      # @example Attach with window handle:
+      #   Watir::Browser.attach(:hwnd, 123456)
+      #
+      # @param [Symbol] how type of the locator. Can be :title, :url or :hwnd.
+      # @param [Symbol] what value of the locator. Can be {String}, {Regexp} or {Fixnum}
+      #   depending of the type parameter.
+      #
+      # @note This method will not work when
+      #   Watir/Ruby is run under a service (instead of a user).
+      def attach(how, what)
+        ie = new true # don't create window
+        ie._attach_init(how, what)
+        ie
+      end
 
-    # Create a new IE window, starting at the specified url.
-    # If no url is given, start empty. Works like IE.start in Watir 1.4.
-    def self.start_window url=nil
-      ie = new_window
-      ie.goto url if url
-      ie
-    end
+      # Yields successively to each IE window on the current desktop. Takes a block.
+      # @note This method will not work when
+      #   Watir/Ruby is run under a service (instead of a user).
+      # @yieldparam [IE] ie instances of IE found.
+      def each
+        shell = WIN32OLE.new('Shell.Application')
+        ie_browsers = []
+        shell.Windows.each do |window|
+          next unless (window.path =~ /Internet Explorer/ rescue false)
+          next unless (hwnd = window.hwnd rescue false)
+          ie = bind(window)
+          ie.hwnd = hwnd
+          ie_browsers << ie
+        end
+        ie_browsers.each do |ie|
+          yield ie
+        end
+      end
 
-    # Create a new IE window in a new process. 
-    # This method will not work when
-    # Watir/Ruby is run under a service (instead of a user).
-    def self.new_process
-      ie = new true
-      ie._new_process_init
-      ie
-    end
+      # @return [String] the IE browser version number as a string.
+      def version
+        @ie_version ||= begin
+                          require 'win32/registry'
+                          ::Win32::Registry::HKEY_LOCAL_MACHINE.open("SOFTWARE\\Microsoft\\Internet Explorer") do |ie_key|
+                            ie_key.read('Version').last
+                          end
+                          # OR: ::WIN32OLE.new("WScript.Shell").RegRead("HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Internet Explorer\\Version")
+                        end
+      end
 
-    def _new_process_init
-      iep = Process.start
-      @ie = iep.window
-      @process_id = iep.process_id
-      initialize_options
-      goto 'about:blank'
-    end
+      # @return [Array<String>] the IE browser version numbers split by "." in an Array.
+      def version_parts
+        version.split('.')
+      end
 
-    # Create a new IE window in a new process, starting at the specified URL. 
-    # Same as IE.start.
-    def self.start_process url=nil
-      ie = new_process
-      ie.goto url if url
-      ie
-    end
+      # Find existing IE window with locators.
+      # @see .attach
+      def find(how, what)
+        ie_ole = _find(how, what)
+        bind ie_ole if ie_ole
+      end
 
-    # Return a Watir::IE object for an existing IE window. Window can be
-    # referenced by url, title, or window handle.
-    # Second argument can be either a string or a regular expression in the 
-    # case of of :url or :title. 
-    # IE.attach(:url, 'http://www.google.com')
-    # IE.attach(:title, 'Google')
-    # IE.attach(:hwnd, 528140)
-    # This method will not work when
-    # Watir/Ruby is run under a service (instead of a user).
-    def self.attach how, what
-      ie = new true # don't create window
-      ie._attach_init(how, what)
-      ie
-    end
+      # Return an IE object that wraps the given window, typically obtained from
+      # Shell.Application.windows.
+      # @private
+      def bind(window)
+        ie = new true
+        ie.ie = window
+        ie.initialize_options
+        ie
+      end
 
-    # this method is used internally to attach to an existing window
-    def _attach_init how, what
-      attach_browser_window how, what
-      initialize_options
-      wait
-    end
+      # @private
+      def _find(how, what)
+        _find_all(how, what).first
+      end
+
+      # @private
+      def _find_all(how, what)
+        ies = []
+        count = -1
+        each do |ie|
+          window = ie.ie
+
+          case how
+          when :url
+            ies << window if (what.matches(window.locationURL))
+          when :title
+            # normal windows explorer shells do not have document
+            # note window.document will fail for "new" browsers
+            begin
+              title = window.locationname
+              title = window.document.title
+            rescue WIN32OLERuntimeError
+            end
+            ies << window if what.matches(title)
+          when :hwnd
+            begin
+              ies << window if what == window.HWND
+            rescue WIN32OLERuntimeError
+            end
+          when :index
+            count += 1
+            if count == what
+              ies << window
+              break
+            end
+          when nil
+            ies << window
+          else
+            raise ArgumentError
+          end
+        end      
+
+        ies
+      end
 
-    # Return an IE object that wraps the given window, typically obtained from
-    # Shell.Application.windows.
-    def self.bind window
-      ie = new true
-      ie.ie = window
-      ie.initialize_options
-      ie
     end
 
-    def initialize_options
-      self.visible = IE.visible
-      self.speed = IE.speed
+    # Used internally to determine when IE has finished loading a page.
+    # @private
+    READYSTATES = {:complete => 4}
 
-      @ole_object = nil
-      @page_container = self
-      @error_checkers = []
-      @activeObjectHighLightColor = HIGHLIGHT_COLOR
-      @url_list = []
+    # The default color for highlighting objects as they are accessed.
+    # @private
+    HIGHLIGHT_COLOR = 'yellow'
+
+    # The time, in seconds, it took for the new page to load after executing
+    # the last command.
+    attr_reader :down_load_time
+
+    # The OLE Internet Explorer object.
+    attr_accessor :ie
+
+    # The list of unique urls that have been visited.
+    attr_reader :url_list
+
+    # @private
+    attr_writer :hwnd
+
+    # Create an IE browser instance.
+    # @param [Boolean] suppress_new_window set to true for not creating a IE
+    #   window.
+    def initialize(suppress_new_window=nil)
+      _new_window_init unless suppress_new_window
     end
 
-    # Specifies the speed that commands will be executed at. Choices are:
+    # Specifies the speed that commands will be executed at.
+    # Possible choices are:
     # * :slow (default)
     # * :fast 
     # * :zippy
-    # With IE#speed=  :zippy, text fields will be entered at once, instead of
-    # character by character (default).
-    def speed= how_fast
+    # 
+    # With :zippy, text fields will be entered at once, instead of
+    # character by character.
+    #
+    # @note :zippy speed does not trigger JavaScript events like onChange etc.
+    #
+    # @param [Symbol] how_fast possible choices are :slow (default), :fast and
+    #   :zippy
+    # @raise [ArgumentError] when invalid speed is specified.
+    def speed=(how_fast)
       case how_fast
-      when :zippy then
+      when :zippy
         @typingspeed = 0
         @pause_after_wait = 0.01
         @type_keys = false
         @speed = :fast
-      when :fast then
+      when :fast
         @typingspeed = 0
         @pause_after_wait = 0.01
         @type_keys = true
         @speed = :fast
-      when :slow then
+      when :slow
         @typingspeed = 0.08
         @pause_after_wait = 0.1
         @type_keys = true
         @speed = :slow
       else
-        raise ArgumentError, "Invalid speed: #{how_fast}"
+        raise ArgumentError, "Invalid speed: #{how_fast}. Possible choices are :slow, :fast and :zippy."
       end
     end
 
+    # @return [Symbol] current speed setting. May be :slow, :fast or :zippy.
     def speed
       return @speed if @speed == :slow
       return @type_keys ? :fast : :zippy
     end
 
-    # deprecated: use speed = :fast instead
+    # @deprecated Use {#speed=} with :fast argument instead.
     def set_fast_speed
+      Kernel.warn "Deprecated(IE.set_fast_speed) - use Browser#speed = :fast instead."
       self.speed = :fast
     end
 
-    # deprecated: use speed = :slow instead    
+    # @deprecated Use {#speed=} with :slow argument instead.
     def set_slow_speed
+      Kernel.warn "Deprecated(IE.set_slow_speed) - use Browser#speed = :slow instead."
       self.speed = :slow
     end
 
+    # @return [Boolean] true when window is visible, false otherwise.
     def visible
       @ie.visible
     end
+    
+    # Set the visibility of IE window.
+    # @param [Boolean] boolean set to true if IE window should be visible, false
+    #   otherwise.
     def visible=(boolean)
       @ie.visible = boolean if boolean != @ie.visible
     end
 
-    # Yields successively to each IE window on the current desktop. Takes a block.
-    # This method will not work when
-    # Watir/Ruby is run under a service (instead of a user).
-    # Yields to the window and its hwnd.
-    def self.each
-      shell = WIN32OLE.new('Shell.Application')
-      ie_browsers = []
-      shell.Windows.each do |window|
-        next unless (window.path =~ /Internet Explorer/ rescue false)
-        next unless (hwnd = window.hwnd rescue false)
-        ie = IE.bind(window)
-        ie.hwnd = hwnd
-        ie_browsers << ie
-      end
-      ie_browsers.each do |ie|
-        yield ie
-      end
-    end
-
-    def self.version
-      @ie_version ||= begin
-                        require 'win32/registry'
-                        ::Win32::Registry::HKEY_LOCAL_MACHINE.open("SOFTWARE\\Microsoft\\Internet Explorer") do |ie_key|
-                          ie_key.read('Version').last
-                        end
-                        # OR: ::WIN32OLE.new("WScript.Shell").RegRead("HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Internet Explorer\\Version")
-                      end
-    end
-
-    def self.version_parts
-      version.split('.')
-    end
-
-    # return internet explorer instance as specified. if none is found,
-    # return nil.
-    # arguments:
-    #   :url, url -- the URL of the IE browser window
-    #   :title, title -- the title of the browser page
-    #   :hwnd, hwnd -- the window handle of the browser window.
-    # This method will not work when
-    # Watir/Ruby is run under a service (instead of a user).
-    def self.find(how, what)
-      ie_ole = IE._find(how, what)
-      IE.bind ie_ole if ie_ole
-    end
-
-    def self._find(how, what)
-      self._find_all(how, what).first
-    end
-
-    def self._find_all(how, what)
-      ies = []
-      count = -1
-      IE.each do |ie|
-        window = ie.ie
-
-        case how
-        when :url
-          ies << window if (what.matches(window.locationURL))
-        when :title
-          # normal windows explorer shells do not have document
-          # note window.document will fail for "new" browsers
-          begin
-            title = window.locationname
-            title = window.document.title
-          rescue WIN32OLERuntimeError
-          end
-          ies << window if what.matches(title)
-        when :hwnd
-          begin
-            ies << window if what == window.HWND
-          rescue WIN32OLERuntimeError
-          end
-        when :index
-          count += 1
-          if count == what
-            ies << window
-            break
-          end
-        when nil
-          ies << window
-        else
-          raise ArgumentError
-        end
-      end      
-
-      ies
-    end
-
-    # Return the current window handle
+    # @return [Fixnum] current IE window handle.
+    # @raise [RuntimeError] when not attached to a browser.
     def hwnd
       raise "Not attached to a browser" if @ie.nil?
       @hwnd ||= @ie.hwnd
     end
-    attr_writer :hwnd
 
+    # @return [Symbol] the name of the browser. Is always :ie.
     def name
       :ie
     end
 
-    # Are we attached to an open browser?
+    # @return [Boolean] true when IE is window exists, false otherwise.
     def exists?
-      begin
-        !!(@ie.name =~ /Internet Explorer/)
-      rescue WIN32OLERuntimeError, NoMethodError
-        false
-      end
+      !!(@ie.name =~ /Internet Explorer/)
+    rescue WIN32OLERuntimeError, NoMethodError
+      false
     end
-    alias :exist? :exists?
 
-    #
-    # Accessing data outside the document
-    #
+    alias :exist? :exists?
 
-    # Return the title of the document
+    # @return [String] the title of the document.
     def title
       @ie.document.title
     end
 
-    # Return the status of the window, typically from the status bar at the bottom.
+    # @return [String] the status text of the window, typically from the status bar at the bottom.
+    #   Will be empty if there's no status or when there are problems accessing status text.
     def status
       @ie.statusText
     rescue WIN32OLERuntimeError
@@ -358,7 +338,8 @@ module Watir
     #
 
     # Navigate to the specified URL.
-    #  * url - string - the URL to navigate to
+    # @param [String] url url to navigate to.
+    # @return [Fixnum] time in seconds the page took to load.
     def goto(url)
       url = "http://" + url unless url =~ %r{://} || url == "about:blank"
       @ie.navigate(url)
@@ -366,22 +347,22 @@ module Watir
       return @down_load_time
     end
 
-    # Go to the previous page - the same as clicking the browsers back button
-    # an WIN32OLERuntimeError exception is raised if the browser cant go back
+    # Go to the previous page - the same as clicking the browsers back button.
+    # @raise [WIN32OLERuntimeError] when the browser can't go back.
     def back
       @ie.GoBack
       wait
     end
 
-    # Go to the next page - the same as clicking the browsers forward button
-    # an WIN32OLERuntimeError exception is raised if the browser cant go forward
+    # Go to the next page - the same as clicking the browsers forward button.
+    # @raise [WIN32OLERuntimeError] when the browser can't go forward.
     def forward
       @ie.GoForward
       wait
     end
 
-    # Refresh the current page - the same as clicking the browsers refresh button
-    # an WIN32OLERuntimeError exception is raised if the browser cant refresh
+    # Refresh the current page - the same as clicking the browsers refresh button.
+    # @raise [WIN32OLERuntimeError] when the browser can't refresh.
     def refresh
       @ie.refresh2(3)
       wait
@@ -391,12 +372,12 @@ module Watir
       '#<%s:0x%x url=%s title=%s>' % [self.class, hash*2, url.inspect, title.inspect]
     end
 
-    # clear the list of urls that we have visited
+    # Clear the list of urls that have been visited.
     def clear_url_list
       @url_list.clear
     end
 
-    # Closes the Browser
+    # Close the {Browser}.
     def close
       return unless exists?
       @ie.stop
@@ -412,95 +393,181 @@ module Watir
       end
     end
 
-    # Maximize the window (expands to fill the screen)
+    # Maximize the window (expands to fill the screen).
     def maximize
       rautomation.maximize
     end
 
-    # Minimize the window (appears as icon on taskbar)
+    # Minimize the window (appears as icon on taskbar).
     def minimize
       rautomation.minimize
     end
 
+    # @return [Boolean] true when window is minimized, false otherwise.
     def minimized?
       rautomation.minimized?
     end
 
-    # Restore the window (after minimizing or maximizing)
+    # Restore the window (after minimizing or maximizing).
     def restore
       rautomation.restore
     end
 
-    # Make the window come to the front
+    # Make the window come to the front.
     def activate
       rautomation.activate
     end
+
     alias :bring_to_front :activate
 
+    # @return [Boolean] true when window is in front e.g. in focus, false otherwise.
     def active?
       rautomation.active?
     end
+
     alias :front? :active?
 
+    # @return [RAutomation::Window] the RAutomation instance for this IE window.
+    # @see https://github.com/jarmo/rautomation
     def rautomation
       @rautomation ||= ::RAutomation::Window.new(:hwnd => hwnd)
-      @rautomation
     end
 
+    # @deprecated use {#rautomation} instead.
     def autoit
-      Kernel.warn "Usage of Watir::IE#autoit method is DEPRECATED! Use Watir::IE#rautomation method instead. Refer to https://github.com/jarmo/RAutomation for updating your scripts."
+      Kernel.warn "Deprecated(IE#autoit) - use IE#rautomation instead. Refer to https://github.com/jarmo/RAutomation for updating your scripts."
       @autoit ||= ::RAutomation::Window.new(:hwnd => hwnd, :adapter => :autoit)
-      @autoit
     end
 
     # Activates the window and sends keys to it.
     #
-    # Example:
-    #   browser.send_keys("Hello World{enter}")
+    # @example
+    #   browser.send_keys("Hello World", :enter)
     #
-    # Refer to RAutomation::Adapter::WinFfi::KeystrokeConverter.convert_special_characters for
-    # special characters conversion.
-    # @see RAutomation::Window#send_keys
+    # @see https://github.com/jarmo/RAutomation/blob/master/lib/rautomation/adapter/win_32/window.rb RAutomation::Window#send_keys documentation.
     def send_keys(*keys)
       rautomation.send_keys *keys
     end
 
-    def dir
-      return File.expand_path(File.dirname(__FILE__))
-    end
-
     #
     # Document and Document Data
     #
 
-    # Return the current document
+    # @return [WIN32OLE] current IE document.
     def document
-      return @ie.document
+      @ie.document
     end
 
-    # returns the current url, as displayed in the address bar of the browser
+    # @return [String] current url, as displayed in the address bar of the browser.
     def url
-      return @ie.LocationURL
+      @ie.LocationURL
     end
 
+    # Create a {Screenshot} instance.
     def screenshot
       Screenshot.new(hwnd)
     end
 
+    # Retrieve a {Window} instance.
+    # 
+    # @example Retrieve a different window without block.
+    #   browser.window(:title => /other window title/).use
+    #   browser.title # => "other window title"
+    #
+    # @example Use different window with block.
+    #   browser.window(:title => /other window title/) do
+    #     browser.title # => "other window title"
+    #   end
+    #   browser.title # => "current window title"
+    #
+    # @param [Hash] specifiers options for finding window.
+    # @option specifiers [String,Regexp] :title Title of the window.
+    # @option specifiers [String,Regexp] :url Url of the window.
+    # @option specifiers [Fixnum] :index The index of the window.
+    # @yield yield optionally to the found window.
+    # @return [Window] found window instance.
     def window(specifiers={}, &blk)
       win = Window.new(self, specifiers, &blk)
       win.use &blk if blk
       win
     end
 
-    def windows(specifiers={}, &blk)
-      self.class._find_all(specifiers.keys.first, specifiers.values.first).map {|ie| Window.new(self, specifiers, IE.bind(ie), &blk)}
+    # @see #window
+    # @return [Array<Window>] array of found windows.
+    def windows(specifiers={})
+      self.class._find_all(specifiers.keys.first, specifiers.values.first).map {|ie| Window.new(self, specifiers, IE.bind(ie))}
     end
 
+    # Retrieve {Cookies} instance.
     def cookies
       Cookies.new(self)
     end
 
+    # Add an error checker that gets executed after every page load, click etc.
+    #
+    # @example
+    #   browser.add_checker lambda { |browser| raise "Error!" if browser.text.include? "Error" }
+    #
+    # @param [Proc] checker Proc object which gets yielded with {IE} instance.
+    def add_checker(checker)
+      @error_checkers << checker
+    end
+
+    # Disable an error checker added via {#add_checker}.
+    #
+    # @param [Proc] checker Proc object to be removed from error checkers.
+    def disable_checker(checker)
+      @error_checkers.delete(checker)
+    end
+
+    # Gives focus to the window frame.
+    def focus
+      active_element = document.activeElement
+      active_element.blur unless active_element.tagName == "BODY"
+      document.focus
+    end
+
+    # @private
+    def attach_command
+      "Watir::IE.attach(:hwnd, #{hwnd})"
+    end
+
+    # @private
+    def _new_window_init
+      create_browser_window
+      initialize_options
+      goto 'about:blank' # this avoids numerous problems caused by lack of a document
+    end
+
+    # @private
+    def _new_process_init
+      iep = Process.start
+      @ie = iep.window
+      @process_id = iep.process_id
+      initialize_options
+      goto 'about:blank'
+    end
+
+    # this method is used internally to attach to an existing window
+    # @private
+    def _attach_init how, what
+      attach_browser_window how, what
+      initialize_options
+      wait
+    end
+
+    # @private
+    def initialize_options
+      self.visible = IE.visible
+      self.speed = IE.speed
+
+      @ole_object = nil
+      @page_container = self
+      @error_checkers = []
+      @active_object_highlight_color = HIGHLIGHT_COLOR
+      @url_list = []
+    end
+
     #
     # Synchronization
     #
@@ -508,9 +575,10 @@ module Watir
     # Block execution until the page has loaded.
     #
     # Will raise Timeout::Error if page hasn't been loaded within 5 minutes.
-    # =nodoc
     # Note: This code needs to be prepared for the ie object to be closed at 
     # any moment!
+    #
+    # @private
     def wait(no_sleep=false)
       @xml_parser_doc = nil
       @down_load_time = 0.0
@@ -562,34 +630,13 @@ module Watir
 
     # Error checkers
 
-    # this method runs the predefined error checks
+    # Run the predefined error checks.
+    #
+    # @private
     def run_error_checks
       @error_checkers.each { |e| e.call(self) }
     end
 
-    # this method is used to add an error checker that gets executed on every page load
-    # *  checker   Proc Object, that contains the code to be run
-    def add_checker(checker)
-      @error_checkers << checker
-    end
-
-    # this allows a checker to be disabled
-    # *  checker   Proc Object, the checker that is to be disabled
-    def disable_checker(checker)
-      @error_checkers.delete(checker)
-    end
-
-    # Gives focus to the frame
-    def focus
-      active_element = document.activeElement
-      active_element.blur unless active_element.tagName == "BODY"
-      document.focus
-    end
-
-    def attach_command
-      "Watir::IE.attach(:hwnd, #{hwnd})"
-    end
-
     private
 
     def create_browser_window
@@ -609,5 +656,6 @@ module Watir
       @ie = ieTemp
     end
 
+
   end # class IE
 end