calabash-cucumber 0.10.0.pre1 → 0.10.0.pre2

data/lib/calabash-cucumber/utils/logging.rb

@@ -2,29 +2,36 @@
 module Calabash
   module Cucumber
 
-    # internal logging methods for calabash-ios gem
+    # Internal logging methods for the calabash-ios gem.
     module Logging
 
-      # controls the the kind of information calabash logs
+      # @!visibility private
+      # Has full console logging been enabled?
       #
-      # this is considered one level above debug logging - maybe we should call
+      # The return value is controlled by the `CALABASH_FULL_CONSOLE_OUTPUT`
+      # environment variable.
+      #
+      # This is considered one level above debug logging - maybe we should call
       # the info log level.
       #
-      # @return [Boolean] +true+ if the <tt>CALABASH_FULL_CONSOLE_OUTPUT</tt> is set to
-      #   '1'
+      # @return [Boolean] Returns `true` if full logging has been enabled.
       def full_console_logging?
         ENV['CALABASH_FULL_CONSOLE_OUTPUT'] == '1'
       end
 
-      # controls whether or not calabash logs debug information
+      # @!visibility private
+      # Has debug logging been enabled?
+      #
+      # The return value is controlled by the `DEBUG` environment variable.
       #
-      # @return [Boolean] +true+ if the <tt>DEBUG</tt> is set to '1'
+      # @return [Boolean] Returns `true` if debug logging has been enabled.
       def debug_logging?
         ENV['DEBUG'] == '1'
       end
 
-      # prints a blue/cyan warning message
+      # Prints a blue warning message.
       # @param [String] msg the message to print
+      # @return [void]
       def calabash_warn(msg)
         begin
           warn "\033[34m\nWARN: #{msg}\033[0m"
@@ -33,8 +40,9 @@ module Calabash
         end
       end
 
-      # prints a green info message
+      # Prints a green info message.
       # @param [String] msg the message to print
+      # @return [void]
       def calabash_info(msg)
         begin
           puts "\033[32m\nINFO: #{msg}\033[0m"
@@ -43,27 +51,33 @@ module Calabash
         end
       end
 
-      # controls printing of deprecation warnings
+      # @!visibility private
+      # Controls printing of deprecation warnings.
       #
-      # to inhibit deprecation message set this to '1'
+      # To inhibit deprecation message set this to '1'
       #
-      # inhibiting deprecation messages is not recommend
+      # Inhibiting deprecation messages is not recommend.
       CALABASH_NO_DEPRECATION = ENV['CALABASH_NO_DEPRECATION'] || '0'
 
-      # returns +true+ if the <tt>CALABASH_NO_DEPRECATION</tt> variable is set
-      # to +1+
+      # @!visibility private
+      # Have deprecation warnings been turned off?
+      #
+      # The return value is controlled but the `CALABASH_NO_DEPRECATION`
+      # environment variable.
       def no_deprecation_warnings?
         ENV['CALABASH_NO_DEPRECATION'] == '1'
       end
 
-      # prints a deprecated message that includes the line number
+      # @!visibility private
+      # Prints a deprecated message that includes the line number.
       #
-      # if ENV['CALABASH_NO_DEPRECATION'] == '1' then this method is a nop
+      # If deprecation warns have been turned off this method does nothing.
       #
       # @param [String] version indicates when the feature was deprecated
       # @param [String] msg deprecation message (possibly suggesting alternatives)
       # @param [Symbol] type { :warn | :pending } - :pending will raise a
       #   cucumber pending exception
+      # @return [void]
       def _deprecated(version, msg, type)
         allowed = [:pending, :warn]
         unless allowed.include?(type)

data/lib/calabash-cucumber/utils/plist_buddy.rb

@@ -5,17 +5,17 @@ module Calabash
 
     include Calabash::Cucumber::Logging
 
-    # module for reading and writing property list values
+    # @!visibility private
+    # A module for reading and writing property list values.
     module PlistBuddy
 
-      # reads +key+ from +file+ and returns the result
+      # Reads key from file and returns the result.
       # @param [String] key the key to inspect (may not be nil or empty)
       # @param [String] file the plist to read
       # @param [Hash] opts options for controlling execution
       # @option opts [Boolean] :verbose (false) controls log level
-      # @return [nil] if +key+ does not exist
-      # @return [String] if the +key+ exists then the value of +key+ (error)
-      # @raise [ArgumentError] if nil or empty +key+
+      # @return [String] the value of the key
+      # @raise [ArgumentError] if nil or empty key
       def plist_read(key, file, opts={})
         if key.nil? or key.length == 0
           raise(ArgumentError, "key '#{key}' must not be nil or empty")
@@ -29,18 +29,17 @@ module Calabash
         end
       end
 
-      # checks if the key exists in plist
+      # Checks if the key exists in plist.
       # @param [String] key the key to inspect (may not be nil or empty)
       # @param [String] file the plist to read
       # @param [Hash] opts options for controlling execution
       # @option opts [Boolean] :verbose (false) controls log level
-      # @return [Boolean] true iff the +key+ exists in plist +file+
+      # @return [Boolean] true if the key exists in plist file
       def plist_key_exists?(key, file, opts={})
         plist_read(key, file, opts) != nil
-
       end
 
-      # replaces or creates the +value+ of +key+ in the +file+
+      # Replaces or creates the value of key in the file.
       #
       # @param [String] key the key to set (may not be nil or empty)
       # @param [String] type the plist type (used only when adding a value)
@@ -48,8 +47,8 @@ module Calabash
       # @param [String] file the plist to read
       # @param [Hash] opts options for controlling execution
       # @option opts [Boolean] :verbose (false) controls log level
-      # @return [Boolean] true iff the operation was successful
-      # @raise [ArgumentError] if nil or empty +key+
+      # @return [Boolean] true if the operation was successful
+      # @raise [ArgumentError] if nil or empty key
       def plist_set(key, type, value, file, opts={})
         default_opts = {:verbose => false}
         merged = default_opts.merge(opts)
@@ -72,7 +71,7 @@ module Calabash
         res == ''
       end
 
-      @private
+      private
 
       # returns the path to the PlistBuddy executable
       # @return [String] path to PlistBuddy
@@ -80,14 +79,14 @@ module Calabash
         '/usr/libexec/PlistBuddy'
       end
 
-      # executes +cmd+ as a shell command and returns the result
+      # Executes cmd as a shell command and returns the result.
       #
       # @param [String] cmd shell command to execute
       # @param [Hash] opts options for controlling execution
       # @option opts [Boolean] :verbose (false) controls log level
       # @return [Boolean] if command was successful
-      # @return [String] if :print'ing result, the value of the key
-      # @return [String] if there is an error, the output from stderr
+      # @return [String] if :print'ing result, the value of the key - if there
+      #   is an error, the output from stderr
       def execute_plist_cmd(cmd, opts={})
         default_opts = {:verbose => false}
         merged = default_opts.merge(opts)
@@ -108,7 +107,7 @@ module Calabash
         res
       end
 
-      # composes a PlistBuddy command that can be executed as a shell command
+      # Composes a PlistBuddy command that can be executed as a shell command.
       #
       # @param [Symbol] type should be one of [:print, :set, :add]
       #
@@ -119,9 +118,9 @@ module Calabash
       #
       # @param [String] file the plist file to interact with (must exist)
       #
-      # @raise [RuntimeError] if +file+ does not exist
-      # @raise [ArgumentError] when invalid +type+ is passed
-      # @raise [ArgumentError] when +args_hash+ does not include required key/value pairs
+      # @raise [RuntimeError] if file does not exist
+      # @raise [ArgumentError] when invalid type is passed
+      # @raise [ArgumentError] when args_hash does not include required key/value pairs
       #
       # @return [String] a shell-ready PlistBuddy command
       def build_plist_cmd(type, args_hash, file)

data/lib/calabash-cucumber/utils/simulator_accessibility.rb

@@ -6,39 +6,42 @@ require 'cfpropertylist'
 module Calabash
   module Cucumber
 
-    # methods for checking and setting simulator accessibility
+    # Public methods for common simulator tasks and private methods for
+    # enabling accessibility on the simulator.
     module SimulatorAccessibility
 
       include Calabash::Cucumber::XcodeTools
       include Calabash::Cucumber::PlistBuddy
 
-      # quits the iOS Simulator
+      # Quits the iOS Simulator.
       #
       # ATM there can only be only simulator open at a time, so simply doing
       # what the sim_launcher gem does:
       #
-      #    def quit_simulator
-      #      `echo 'application "iPhone Simulator" quit' | osascript`
-      #    end
+      # ```
+      # def quit_simulator
+      #   `echo 'application "iPhone Simulator" quit' | osascript`
+      # end
+      # ```
       #
       # works.  I am not sure if we will ever be able to launch more than one
       # simulator, but in case we can, this method will quit the simulator
-      # that is indicated by +xcode-select+ or +DEVELOPER_DIR+.
+      # that is indicated by `xcode-select` or `DEVELOPER_DIR`.
       def quit_simulator
         dev_dir = xcode_developer_dir
         system "/usr/bin/osascript -e 'tell application \"#{dev_dir}/Platforms/iPhoneSimulator.platform/Developer/Applications/iPhone Simulator.app\" to quit'"
       end
 
-      # launches the iOS Simulator indicated by +xcode-select+ or +DEVELOPER_DIR+
+      # Launches the iOS Simulator indicated by `xcode-select` or `DEVELOPER_DIR`.
       def launch_simulator
         dev_dir = xcode_developer_dir
         system "open -a \"#{dev_dir}/Platforms/iPhoneSimulator.platform/Developer/Applications/iPhone Simulator.app\""
       end
 
-      # resets the simulator content and settings.  it is analogous to touching
+      # Resets the simulator content and settings.  It is analogous to touching
       # the menu item.
       #
-      # it works by deleting the following directories:
+      # It works by deleting the following directories:
       #
       # * ~/Library/Application Support/iPhone Simulator/Library
       # * ~/Library/Application Support/iPhone Simulator/Library/<sdk>[-64]
@@ -78,10 +81,11 @@ module Calabash
         end
       end
 
-      # enables accessibility on any existing iOS Simulator by adjusting the
+      # @!visibility private
+      # Enables accessibility on any existing iOS Simulator by adjusting the
       # simulator's Library/Preferences/com.apple.Accessibility.plist contents.
       #
-      # a simulator 'exists' if has an Application Support directory. for
+      # A simulator 'exists' if has an Application Support directory. for
       # example, the 6.1, 7.0.3-64, and 7.1 simulators exist if the following
       # directories are present:
       #
@@ -89,15 +93,15 @@ module Calabash
       #     ~/Library/Application Support/iPhone Simulator/Library/7.0.3-64
       #     ~/Library/Application Support/iPhone Simulator/Library/7.1
       #
-      # a simulator is 'possible' if the SDK is available in the Xcode version.
+      # A simulator is 'possible' if the SDK is available in the Xcode version.
       #
-      # this method merges (uniquely) the possible and existing SDKs.
+      # This method merges (uniquely) the possible and existing SDKs.
       #
-      # this method also hides the AXInspector.
+      # This method also hides the AXInspector.
       #
       # @param [Hash] opts controls the behavior of the method
       # @option opts [Boolean] :verbose controls logging output
-      # @return [Boolean] true iff enabling accessibility worked on all sdk
+      # @return [Boolean] true if enabling accessibility worked on all sdk
       #  directories
       def enable_accessibility_on_simulators(opts={})
         possible = possible_simulator_support_sdk_dirs
@@ -111,17 +115,18 @@ module Calabash
 
       @private
 
-      # enables accessibility on the simulator indicated by
-      # +sim_app_support_sdk_dir+.
+      # @!visibility private
+      # Enables accessibility on the simulator indicated by `sim_app_support_sdk_dir.`
       #
-      # WARNING:  this will quit the simulator
+      # @note  This will quit the simulator.
       #
+      # @example
       #   path = '/6.1'
       #   enable_accessibility_in_sdk_dir(path)
       #
-      # this method also hides the AXInspector.
+      # This method also hides the AXInspector.
       #
-      # if the Library/Preferences/com.apple.Accessibility.plist does not exist
+      # If the Library/Preferences/com.apple.Accessibility.plist does not exist
       # this method will create a Library/Preferences/com.apple.Accessibility.plist
       # that (oddly) the Simulator will _not_ overwrite.
       #
@@ -132,7 +137,7 @@ module Calabash
       #
       # @param [Hash] opts controls the behavior of the method
       # @option opts [Boolean] :verbose controls logging output
-      # @return [Boolean] iff the plist exists and the plist was successfully
+      # @return [Boolean] if the plist exists and the plist was successfully
       #   updated.
       def enable_accessibility_in_sdk_dir(sim_app_support_sdk_dir, opts={})
         default_opts = {:verbose => false}
@@ -182,7 +187,8 @@ module Calabash
       end
 
 
-      # a hash table of the accessibility properties that control whether or not
+      # @!visibility private
+      # A hash table of the accessibility properties that control whether or not
       # accessibility is enabled and whether the AXInspector is visible.
       # @return [Hash] table of accessibility properties found in the
       #  Library/Preferences/com.apple.Accessibility.plist
@@ -220,22 +226,25 @@ module Calabash
         }
       end
 
-      # the absolute path to the iPhone Simulator Application Support directory
+      # @!visibility private
+      # The absolute path to the iPhone Simulator Application Support directory.
       # @return [String] absolute path
       def simulator_app_support_dir
         File.expand_path('~/Library/Application Support/iPhone Simulator')
       end
 
-      # the absolute path to the SDK's com.apple.Accessibility.plist file
+      # @!visibility private
+      # The absolute path to the SDK's com.apple.Accessibility.plist file.
       # @param [String] sdk_dir base path the SDK directory
       # @return [String] an absolute path
       def plist_path_with_sdk_dir(sdk_dir)
         File.expand_path("#{sdk_dir}/Library/Preferences/com.apple.Accessibility.plist")
       end
 
-      # returns a list of absolute paths the existing simulator directories.
+      # @!visibility private
+      # Returns a list of absolute paths the existing simulator directories.
       #
-      # a simulator 'exists' if has an Application Support directory. for
+      # A simulator 'exists' if has an Application Support directory. for
       # example, the 6.1, 7.0.3-64, and 7.1 simulators exist if the following
       # directories are present:
       #
@@ -251,13 +260,14 @@ module Calabash
         }
       end
 
-      # returns a list of possible SDKs per Xcode version
+      # @!visibility private
+      # Returns a list of possible SDKs per Xcode version.
       #
-      # it is not enough to ask for the available sdks because of the new 64-bit
+      # It is not enough to ask for the available sdks because of the new 64-bit
       # variants that started to appear Xcode 5 and the potential for patch level
       # versions.
       #
-      # unfortunately, this method will need be maintained per Xcode version.
+      # Unfortunately, this method will need be maintained per Xcode version.
       #
       # @return [Array<String>] ex. ['6.1', '7.1', '7.0.3', '7.0.3-64']
       def possible_simulator_sdks
@@ -290,7 +300,8 @@ module Calabash
         (available - ['7.0']).uniq.sort
       end
 
-      # return absolute paths to possible simulator support sdk dirs
+      # @!visibility private
+      # Return absolute paths to possible simulator support sdk dirs.
       #
       # these directories may or may not exist
       # @return [Array<String>] an array of absolute paths

data/lib/calabash-cucumber/utils/xctools.rb

@@ -3,15 +3,21 @@ require 'open3'
 module Calabash
   module Cucumber
 
-    # methods for interacting with the xcode tools
+    # @!visibility private
+    # Methods for interacting with the xcode tools.
     module XcodeTools
 
-      # returns the path to the current developer directory
+      # Returns the path to the current developer directory.
       #
+      # From the man pages:
+      #
+      # ```
       # $ man xcode-select
       # DEVELOPER_DIR
-      # Overrides the active developer directory. When DEVELOPER_DIR is set, its value
-      # will be used instead of the system-wide active developer directory.
+      # Overrides the active developer directory. When DEVELOPER_DIR is set,
+      # its value will be used instead of the system-wide active developer
+      # directory.
+      #```
       #
       # @return [String] path to current developer directory
       def xcode_developer_dir
@@ -21,17 +27,22 @@ module Calabash
         `xcode-select --print-path`.chomp
       end
 
-      # returns the path to the current developer usr/bin directory
+      # Returns the path to the current developer `usr/bin` directory.
       # @return [String] path to the current xcode binaries
       def xcode_bin_dir
-        "#{xcode_developer_dir}/usr/bin"
+        File.expand_path("#{xcode_developer_dir}/usr/bin")
       end
 
-      # method for interacting with instruments
+      # Method for interacting with instruments.
+      #
+      # @example Getting the path to instruments.
+      #  instruments #=> /Applications/Xcode.app/Contents/Developer/usr/bin/instruments
+      #
+      # @example Getting a the version of instruments.
+      #  instruments(:version) #=> 5.1.1
       #
-      #              instruments #=> /Applications/Xcode.app/Contents/Developer/usr/bin/instruments
-      #    instruments(:version) #=> 5.1.1
-      #       instruments(:sims) #=> < list of known simulators >
+      # @example Getting list of known simulators.
+      #  instruments(:sims) #=> < list of known simulators >
       #
       # @param [String] cmd controls the return value.  currently accepts nil,
       #   :sims, and :version as valid parameters
@@ -58,15 +69,17 @@ module Calabash
         end
       end
 
-      # does the instruments +version+ accept the -s (devices) flag?
+      # Does the instruments `version` accept the -s flag?
       #
-      #     instruments_supports_hyphen_s?('4.6.3') #=> false
-      #     instruments_supports_hyphen_s?('5.0.2') #=> true
-      #       instruments_supports_hyphen_s?('5.1') #=> true
+      # @example
+      #  instruments_supports_hyphen_s?('4.6.3') => false
+      #  instruments_supports_hyphen_s?('5.0.2') => true
+      #  instruments_supports_hyphen_s?('5.1')   => true
       #
-      # @param [String] version a major.minor.{patch} version string - defaults
-      #  to the currently active instruments binary
-      # @return [Boolean] true iff the version is >= 5.*
+      # @param [String] version (instruments(:version))
+      #   a major.minor[.patch] version string
+      #
+      # @return [Boolean] true if the version is >= 5.*
       def instruments_supports_hyphen_s?(version=instruments(:version))
         tokens = version.split('.')
         return false if tokens[0].to_i < 5
@@ -74,10 +87,7 @@ module Calabash
         true
       end
 
-      # returns a list of installed simulators by calling:
-      #
-      #    $ instruments -s devices
-      #
+      # Returns a list of installed simulators by calling `$ instruments -s devices`.
       # and parsing the output
       # @return [Array<String>] an array of simulator names suitable for passing
       #   to instruments or xcodebuild