spec: tweak fj cop wording, add better comments to methods

Change-Id: I1121976674f2ed45a9838f1a8533731765844d2d
Reviewed-on: https://gerrit.instructure.com/78303
Tested-by: Jenkins
Reviewed-by: Landon Wilkins <lwilkins@instructure.com>
Product-Review: Landon Wilkins <lwilkins@instructure.com>
QA-Review: Landon Wilkins <lwilkins@instructure.com>

Author: jenseng

gems/rubocop-canvas/lib/rubocop_canvas/cops/specs/prefer_f_over_fj.rb

@@ -28,9 +28,7 @@ def error_msg(method)
           alternative = SUSPECT_METHOD_NAMES[method]
           "Prefer `#{alternative}` instead of `#{method}`; `#{method}`"\
             " should only be used if you are doing jquery-fake-css selectors"\
-            " (e.g. `:visible`). Unlike `#{alternative}`, `#{method}`"\
-            " will not wait for the element to appear in the DOM,"\
-            " often contributing to flickering failures."
+            " (e.g. `:visible`)"
         end
 
         def autocorrect(node)

spec/selenium/test_setup/common_helper_methods/custom_selenium_actions.rb

@@ -32,7 +32,10 @@ def find_radio_button_by_value(value, scope = nil)
     fj("input[type=radio][value=#{value}]", scope)
   end
 
-  # f means "find" this is a shortcut to finding elements
+  # find an element via css selector
+  #
+  # like other selenium methods, this will wait until it finds the
+  # element on the page
   def f(selector, scope = nil)
     raise 'need to do a get to use find' unless @click_ready
     begin
@@ -52,7 +55,13 @@ def fln(link_text, scope = nil)
     end
   end
 
-  # short for find with jquery
+  # find an element via fake-jquery-css selector
+  #
+  # useful for fake-jquery-css like `:visible`. if you're using
+  # vanilla css, prefer `f` over `fj`.
+  #
+  # like other selenium methods, this will wait until it finds the
+  # element on the page
   def fj(selector, scope = nil)
     raise 'need to do a get to use find' unless @click_ready
     begin