Implement getAttribute for W3C-compliant remote ends.

Fix docs for WebElement.getAttribute to attempt to better reflect reality. This shim is supposed to replicate the OSS behavior, but in terms of W3C-compliant "Get Element Attribute" and "Get Element Property" commands. (See appium#2301.)

Author: juangj

src/main/java/org/openqa/selenium/WebElement.java

@@ -87,28 +87,37 @@ public interface WebElement extends SearchContext, TakesScreenshot {
  String getTagName();
 
  /**
- * Get the value of a the given attribute of the element. Will return the current value, even if
- * this has been modified after the page has been loaded. More exactly, this method will return
- * the value of the given attribute, unless that attribute is not present, in which case the value
- * of the property with the same name is returned (for example for the "value" property of a
- * textarea element). If neither value is set, null is returned. The "style" attribute is
- * converted as best can be to a text representation with a trailing semi-colon. The following are
- * deemed to be "boolean" attributes, and will return either "true" or null:
- * <p>
- * async, autofocus, autoplay, checked, compact, complete, controls, declare, defaultchecked,
+ * Get the value of the given attribute of the element. Will return the current value, even if
+ * this has been modified after the page has been loaded.
+ *
+ * <p>More exactly, this method will return the value of the property with the given name, if it
+ * exists. If it does not, then the value of the attribute with the given name is returned. If
+ * neither exists, null is returned.
+ *
+ * <p>The "style" attribute is converted as best can be to a text representation with a trailing
+ * semi-colon.
+ *
+ * <p>The following are deemed to be "boolean" attributes, and will return either "true" or null:
+ *
+ * <p>async, autofocus, autoplay, checked, compact, complete, controls, declare, defaultchecked,
  * defaultselected, defer, disabled, draggable, ended, formnovalidate, hidden, indeterminate,
  * iscontenteditable, ismap, itemscope, loop, multiple, muted, nohref, noresize, noshade,
  * novalidate, nowrap, open, paused, pubdate, readonly, required, reversed, scoped, seamless,
- * seeking, selected, spellcheck, truespeed, willvalidate
- * <p>
- * Finally, the following commonly mis-capitalized attribute/property names are evaluated as
+ * seeking, selected, truespeed, willvalidate
+ *
+ * <p>Finally, the following commonly mis-capitalized attribute/property names are evaluated as
  * expected:
- * <p>
+ *
  * <ul>
- * <li>"class"
- * <li>"readonly"
+ * <li>If the given name is "class", the "className" property is returned.
+ * <li>If the given name is "readonly", the "readOnly" property is returned.
  * </ul>
  *
+ * <i>Note:</i> The reason for this behavior is that users frequently confuse attributes and
+ * properties. If you need to do something more precise, e.g., refer to an attribute even when a
+ * property of the same name exists, then you should evaluate Javascript to obtain the result
+ * you desire.
+ *
  * @param name The name of the attribute.
  * @return The attribute/property's current value or null if the value is not set.
  */