lib/calabash-cucumber/map.rb in calabash-cucumber-0.14.3 vs lib/calabash-cucumber/map.rb in calabash-cucumber-0.15.0

@@ -4,66 +4,74 @@
   module Cucumber
 
     # @!visibility private
     module Map
 
-      # returns an array of views matched by the `query` or the result of
+      # Returns an array of views matched by the `query` or the result of
       # performing the Objective-C sequence defined by the `method_name` and
-      # `method_args` on all the views matched by the `query`
+      # `method_args` on all the views matched by the `query`.
       #
-      # the query language is documented here: https://github.com/calabash/calabash-ios/wiki
+      # This is not a method that users should be calling directly.
       #
-      # returns a JSON representation of each view that is matched
+      # The `method_name` is typically mapped to an LPOperation on the server.
+      # Some examples of LPOperations are:
       #
-      # when the `method_name` is a calabash operation, returns an array that
-      # contains the result of calling the objc selector `description` on each
-      # matched view.  these are examples of calabash operations: `:flash`,
-      # `:scrollToRowWithMark`, `:changeDatePickerDate`.
+      #   * :flash
+      #   * :scrollToRowWithMark
+      #   * :changeDatePickerDate
+      #
+      # If `method_name` maps to no LPOperation, then it is treated a selector
+      # and is performed on any view that matches `query`.
+      #
+      # @examples
+      #
+      #   # Calls 'text' on any visible UITextField, because :text is not a defined operation.
+      #   > map("textField", :text)
+      #   => [ "old text" ]
+      #
+      #   # Does not call 'setText:', because :setText is a defined operation.
+      #   > map("textField", :setText, 'new text')
+      #   => [ <UITextField ... > ]
+      #
+      #   # Calls 'setText:', because 'setText:' is not a defined operation.
+      #   > map("textField", 'setText:', 'newer text')
+      #   => [ "<VOID>" ]
+      #
+      #   # Will return [] because :unknownSelector is not defined on UITextField.
+      #   > map("textField", :unknownSelector)
+      #   => []
+      #
+      #   # Will return [] because 'setAlpha' requires 1 argument and none was provided.
+      #   # An error will be logged by the server in the device logs.
+      #   > map("textField", 'setAlpha:')
+      #   => []
+      #
+      #
+      # Well behaved LPOperations should return the view as JSON objects.
+      #
+      # @todo Calabash LPOperations should return 'views touched' in JSON format
       def map(query, method_name, *method_args)
-        #todo calabash operations should return 'views touched' in JSON format
         raw_map(query, method_name, *method_args)['results']
       end
 
-      # returns a JSON object the represents the result of performing an http
+      # Returns a JSON object the represents the result of performing an http
       # query against the calabash server.
       #
-      # gem users should _not_ call this method directly; call `map` instead.
-      #
-      # raises an error and takes a screenshot if the value of the `outcome` key
+      # Raises an error and takes a screenshot if the value of the `outcome` key
       # is _not_ 'SUCCESS'
       #
-      # the JSON object contains the following keys:
+      # The JSON object contains the following keys:
       #
       #     `outcome` => indicates the success or failure of the query
       #
       #     `status_bar_orientation` => the orientation of the status bar
       #
       #     `results` => views matched by the `query` or the result of
       #                  performing the Objective-C selector sequence defined by
       #                  the `method_name` with arguments defined in
       #                  `method_args` on all views matched by the `query`
       #
-      # the query language is documented here: https://github.com/calabash/calabash-ios/wiki
-      #
-      # here are some examples that clarify how the `method_name` and `method_args`
-      # influence the value of the `results` key
-      #
-      # simple examples:
-      #
-      #    raw_map('label')['result'] #=> [ all visible UILabels ]
-      #       raw_map('label', :text) #=> [ the 'text' of all visible UILabels ]
-      #
-      # example of calling a selector with arguments:
-      #
-      # <tt>raw_map("tableView marked:'cheeses'", {'numberOfRowsInSection' => 0})) =></tt>
-      # <tt>[ the number of rows in the first section of the 'cheeses' table ]</tt>
-      #
-      # example of calling a selector on view to return an object and then calling
-      # another selector on the returned object:
-      #
-      # <tt>raw_map("pickerView marked:'cheeses'", :delegate, [{pickerView:nil},{titleForRow:1},{forComponent:0}]) =></tt>
-      # objc call: <tt>[[pickerView delegate] pickerView:nil titleForRow:1 forComponent:0] =></tt>
-      # <tt>['French']</tt>
+      # @see Calabash::Cucumber::Map#map for examples.
       def raw_map(query, method_name, *method_args)
         operation_map = {
             :method_name => method_name,
             :arguments => method_args
         }