docs: fixup data-targets selectors, clarify docs

Author: keithamus

docs/_guide/anti-patterns.md

@@ -250,15 +250,15 @@ class UserFilter {
 <user-list>
   <label><input type="checkbox"
     data-action="change:user-list.filter"
-    data-target="user-list.filters"
+    data-targets="user-list.filters"
     data-filter="all">Show all</label>
   <label><input type="checkbox"
     data-action="change:user-list.filter"
-    data-target="user-list.filters"
+    data-targets="user-list.filters"
     data-filter="new">New Users</label>
   <label><input type="checkbox"
     data-action="change:user-list.filter"
-    data-target="user-list.filters"
+    data-targets="user-list.filters"
     data-filter="admin">Admins</label>
   <!-- ... --->
 </user-filter>
@@ -290,15 +290,16 @@ class UserFilter {
 <user-filter>
   <label><input type="checkbox"
     data-action="change:user-list.filter"
-    data-target="user-list.filters user-list.allFilter"
+    data-target="user-list.allFilter"
+    data-targets="user-list.filters"
     data-filter="all">Show all</label>
   <label><input type="checkbox"
     data-action="change:user-list.filter"
-    data-target="user-list.filters"
+    data-targets="user-list.filters"
     data-filter="new">New Users</label>
   <label><input type="checkbox"
     data-action="change:user-list.filter"
-    data-target="user-list.filters"
+    data-targets="user-list.filters"
     data-filter="admin">Admins</label>
   <!-- ... --->
 </user-filter>

docs/_guide/conventions.md

@@ -35,3 +35,7 @@ Be careful not to go too short! We'd recommend avoiding contracting words such a
 ### Method names should describe what they do
 
 A good method name, much like a good class name, describes what it does, not how it was invoked. While methods can be given any name, names like `onClick` are best avoided, overly generic names like `toggle` should also be avoided. Just like class names it is a good idea to ask "how" and "what", so for example `showAdmins`, `filterUsers`, `updateURL`.
+
+### `@target` should use singular naming, while `@targets` should use plural
+
+To help differentiate the two `@target`/`@targets` decorators, the properties should be named with respective to their cardinality. That is to say, if you're using an `@target` decorator, then the name should be singular (e.g. `user`, `field`) while the `@targets` decorator should be coupled with plural property names (e.g. `users`, `fields`).

docs/_guide/targets.md

@@ -66,20 +66,20 @@ Remember! There are two decorators available, `@target` which fetches only one e
   </div>
 </div>
 
-The `@target` decorator will only ever return _one_ element, just like `querySelector`. If you want to get multiple Targets, you need the `@targets` decorator which works almost identically, but it'll return an _array_ of elements. To put this into types: `@target` returns `Element|undefined` while `@targets` returns `Array<Element>`
+The `@target` decorator will only ever return _one_ element, just like `querySelector`. If you want to get multiple Targets, you need the `@targets` decorator which works almost the same, but returns an Array of elements, and it searches the `data-targets` attribute (not `data-target`). To put this into types: `@target` returns `Element|undefined` while `@targets` returns `Array<Element>`
 
 Elements can be referenced as multiple targets, and targets may be referenced multiple times within the HTML:
 
 ```html
 <team-members>
   <user-list>
-    <user-settings data-target="user-list.user">
-      <input type="checkbox" data-target="team-members.read user-settings.read">
-      <input type="checkbox" data-target="team-members.write user-settings.write">
+    <user-settings data-targets="user-list.users">
+      <input type="checkbox" data-targets="team-members.reads user-settings.reads">
+      <input type="checkbox" data-targets="team-members.writes user-settings.writes">
     </user-settings>
-    <user-settings data-target="user-list.user">
-      <input type="checkbox" data-target="team-members.read user-settings.read">
-      <input type="checkbox" data-target="team-members.write user-settings.write">
+    <user-settings data-targets="user-list.users">
+      <input type="checkbox" data-targets="team-members.reads user-settings.reads">
+      <input type="checkbox" data-targets="team-members.writes user-settings.writes">
     </user-settings>
   </user-list>
 </team-members>
@@ -119,7 +119,7 @@ To clarify the difference between `@target` and `@targets` here is a handy table
 | Decorator  | Equivalent Native Method | Selector           | Returns          | 
 |:-----------|:-------------------------|:-------------------|:-----------------|
 | `@target`  | `querySelector`          | `data-target="*"`  | `Element`        | 
-| `@targets` | `querySelectorAll`       | `data-target="*"`  | `Array<Element>` | 
+| `@targets` | `querySelectorAll`       | `data-targets="*"` | `Array<Element>` | 
 
 ### What about without Decorators?