update documentation and comments

Author: KazuCocoa

README.md

@@ -6,7 +6,7 @@
 
 - http://www.rubydoc.info/github/appium/ruby_lib_core
 
-# base library
+# Used main library
 - https://github.com/appium/ruby_lib
 
 # How to start
@@ -18,13 +18,47 @@ $ appium
 ```
 
 ## Run tests
+### Unit Tests
 
 ```bash
 $ bundle install
-$ rake test:func:android # Andorid
+$ rake test:unit
+```
+
+### Functional Tests
+
+```bash
+$ bundle install
+$ rake test:func:android # Andorid 
 $ rake test:func:ios     # iOS
 ```
 
+# How to use this core library
+1. Launch the appium server locally.
+2. Run the following script.
+
+```ruby
+require 'rubygems'
+require 'appium_lib_core'
+
+opts = {
+       caps: {
+         platformName: :ios,
+         platformVersion: '11.0',
+         deviceName: 'iPhone Simulator',
+         automationName: 'XCUITest',
+         app: '/path/to/MyiOS.app'
+       },
+       appium_lib: {
+       }
+     }
+@core = Appium::Driver.new(opts) # core driver
+@driver = @core.start_driver     # driver extend selenium-webdriver
+
+# Launch iPhone Simulator and `MyiOS.app`
+@driver.find_element(:accessibility_id, 'some accessibility') # find an element
+```
+
 # Release
 
 ```bash

lib/appium_lib_core/driver.rb

@@ -18,41 +18,42 @@ class Driver
       # @return [Hash]
       attr_reader :automation_name
 
-      # Custom URL for the selenium server. If set this attribute, ruby_lib try to handshake to the custom url.
+      # Custom URL for the selenium server. If set this attribute, ruby_lib_core try to handshake to the custom url.
+      # False is by default and then "http://127.0.0.1:#{@port}/wd/hub" is used.
       # @return [String]
       attr_reader :custom_url
 
-      # Export session id to textfile in /tmp for 3rd party tools
+      # Export session id to textfile in /tmp for 3rd party tools. False bu default.
       # @return [Boolean]
       attr_reader :export_session
       # @return [String] By default, session id is exported in '/tmp/appium_lib_session'
       attr_reader :export_session_path
 
       # Default wait time for elements to appear
-      # Returns the default client side wait.
-      # This value is independent of what the server is using
-      # Provide Appium::Drive like { appium_lib: { wait: 20 } }
+      # Returns the default client side wait. 20 second is by default.
+      # Provide Appium::Drive like { appium_lib: { wait: 30 } }
       # @return [Integer]
       attr_reader :default_wait
 
-      # Appium's server port
+      # Appium's server port. 4723 is by default.
       # Provide Appium::Drive like { appium_lib: { port: 8080 } }
       # @return [Integer]
       attr_reader :port
 
-      # Return a time wait timeout
+      # Return a time wait timeout. 30 second is by default.
       # Wait time for ::Appium::Core::Base::Wait, wait and wait_true
       # Provide Appium::Drive like { appium_lib: { wait_timeout: 20 } }
       # @return [Integer]
       attr_reader :wait_timeout
 
-      # Return a time wait timeout
+      # Return a time to wait interval. 0.5 second is by default.
       # Wait interval time for ::Appium::Core::Base::Wait, wait and wait_true
-      # Provide Appium::Drive like { appium_lib: { wait_interval: 20 } }
+      # Provide Appium::Drive like { appium_lib: { wait_interval: 0.1 } }
       # @return [Integer]
       attr_reader :wait_interval
 
       # instance of AbstractEventListener for logging support
+      # Nil by default
       attr_reader :listener
 
       # @return [Appium::Core::Base::Driver]
@@ -66,12 +67,15 @@ class Driver
       # @example
       #
       #     require 'rubygems'
-      #     require 'appium_lib'
+      #     require 'appium_lib_core'
       #
       #     # Start iOS driver
       #     opts = {
       #              caps: {
       #                platformName: :ios,
+      #                platformVersion: '11.0',
+      #                deviceName: 'iPhone Simulator',
+      #                automationName: 'XCUITest',
       #                app: '/path/to/MyiOS.app'
       #              },
       #              appium_lib: {
@@ -84,8 +88,8 @@ class Driver
       #                listener: nil,
       #              }
       #            }
-      #     @core_driver = Appium::Core.for(self, opts) # create a core driver with `opts` and extend methods into `self`
-      #     @core_driver.start_driver(server_url: server_url, http_client_ops: http_client_ops) # start driver
+      #     @core = Appium::Core.for(self, opts) # create a core driver with `opts` and extend methods into `self`
+      #     @core.start_driver(server_url: server_url) # start driver
       #
       def self.for(target, opts = {})
         new(target, opts)
@@ -120,24 +124,23 @@ def initialize(target, opts = {})
       # @example
       #
       #     require 'rubygems'
-      #     require 'appium_lib'
+      #     require 'appium_lib_core'
       #
       #     # platformName takes a string or a symbol.
       #
       #     # Start iOS driver
       #     opts = {
       #              caps: {
       #                platformName: :ios,
+      #                platformVersion: '11.0',
+      #                deviceName: 'iPhone Simulator',
+      #                automationName: 'XCUITest',
       #                app: '/path/to/MyiOS.app'
       #              },
       #              appium_lib: {
-      #                server_url: "http://custom-host:8080/wd/hub.com",
-      #                export_session: false,
-      #                port: 8080,
-      #                wait: 0,
+      #                wait: 20,
       #                wait_timeout: 20,
       #                wait_interval: 0.3,
-      #                listener: nil,
       #              }
       #            }
       #     @core = Appium::Driver.new(opts)
@@ -407,7 +410,7 @@ def set_app_path
       # @private
       def set_appium_lib_specific_values(appium_lib_opts)
         @custom_url = appium_lib_opts.fetch :server_url, false
-        @default_wait = appium_lib_opts.fetch :wait, 0
+        @default_wait = appium_lib_opts.fetch :wait, 20
 
         # bump current session id into a particular file
         @export_session = appium_lib_opts.fetch :export_session, false

test/test_helper.rb

@@ -10,6 +10,7 @@
 
 class AppiumLibCoreTest
   module Caps
+    # Require a simulator which OS version is 10.3, for example.
     IOS_OPS = {
       caps: {
         platformName: :ios,
@@ -28,6 +29,8 @@ module Caps
       }
     }.freeze
 
+    # Require a real device or an emulator.
+    # We should update platformVersion and deviceName to fit your environment.
     ANDROID_OPS = {
       caps: {
         platformName: :android,