Documntation updates

README.md

@@ -926,12 +926,17 @@ Capybara.default_selector = :xpath
 find('.//ul/li').text
 ```
 
-Capybara allows you to add custom selectors, which can be very useful if you
-find yourself using the same kinds of selectors very often:
+Capybara provides a number of other built-in selector types. The full list, along
+with applicable filters, can be seen at [built-in selectors](https://www.rubydoc.info/github/teamcapybara/capybara/Capybara/Selector)
+
+Capybara also allows you to add custom selectors, which can be very useful if you
+find yourself using the same kinds of selectors very often. The examples below are very
+simple, and there are many available features not demonstrated. For more in-depth examples
+please see Capybaras built-in selector definitions.
 
 ```ruby
-Capybara.add_selector(:id) do
-  xpath { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }
+Capybara.add_selector(:my_attribute) do
+  xpath { |id| XPath.descendant[XPath.attr(:my_attribute) == id.to_s] }
 end
 
 Capybara.add_selector(:row) do
@@ -948,9 +953,9 @@ an XPath expression generated through the XPath gem. You can now use these
 selectors like this:
 
 ```ruby
-find(:id, 'post_123')
-find(:row, 3)
-find(:flash_type, :notice)
+find(:my_attribute, 'post_123') # find element with matching attribute
+find(:row, 3) # find 3rd row in table body
+find(:flash_type, :notice) # find element with id of 'flash' and class of 'notice'
 ```
 
 ## <a name="beware-the-xpath--trap"></a>Beware the XPath // trap

lib/capybara/selector.rb

@@ -35,13 +35,13 @@ require 'capybara/selector/definition'
 #       * :multiple (Boolean) - Match fields that accept multiple values
 #
 # * **:fieldset** - Select fieldset elements
-#   * Locator: Matches id or contents of wrapped legend
+#   * Locator: Matches id, {Capybara.configure test_id}, or contents of wrapped legend
 #   * Filters:
 #       * :legend (String) - Matches contents of wrapped legend
 #       * :disabled (Boolean) - Match disabled fieldset?
 #
 # * **:link** - Find links (`<a>` elements with an href attribute)
-#   * Locator: Matches the id or title attributes, or the string content of the link, or the alt attribute of a contained img element.
+#   * Locator: Matches the id, {Capybara.configure test_id}, or title attributes, or the string content of the link, or the alt attribute of a contained img element.
 #     By default this selector requires a link to have an href attribute.
 #   * Filters:
 #       * :title (String) - Matches the title attribute
@@ -132,12 +132,12 @@ require 'capybara/selector/definition'
 #       * :multiple (Boolean) - Match field that accepts multiple values
 #
 # * **:label** - Find label elements
-#   * Locator: Match id or text contents
+#   * Locator: Match id, {Capybara.configure test_id}, or text contents
 #   * Filters:
 #       * :for (Element, String, Regexp) - The element or id of the element associated with the label
 #
 # * **:table** - Find table elements
-#   * Locator: id or caption text of table
+#   * Locator: id, {Capybara.configure test_id}, or caption text of table
 #   * Filters:
 #       * :caption (String) - Match text of associated caption
 #       * :with_rows (Array<Array<String>>, Array<Hash<String, String>>) - Partial match `<td>` data - visibility of `<td>` elements is not considered