Improve the documentation of ignored users

* Fix the event schema to represent the real world
* Add the module to the spec targets
* Remove incomplete thought from the client behaviour
* Link to the account data API
* Minor word choice changes

Signed-off-by: Travis Ralston <travpc@gmail.com>

event-schemas/schema/m.ignored_user_list

@@ -7,12 +7,17 @@ description: |-
 properties:
   content:
     type: object
-    patternProperties:
+    properties:
-      "^@":
+      ignored_users:
-        type: "object"
+        type: object
-        title: "Ignored User"
+        patternProperties:
-        description: "An empty object for future enhancement"
+          "^@":
-        x-pattern: "$USER_ID"
+            type: "object"
+            title: "Ignored User"
+            description: "An empty object for future enhancement"
+            x-pattern: "$USER_ID"
+      required:
+        - ignored_users
   type:
     enum:
       - m.ignored_user_list

specification/modules/ignore_users.rst

@@ -12,7 +12,7 @@
 .. See the License for the specific language governing permissions and
 .. limitations under the License.
 
-Ignore Users
+Ignoring Users
 ==============
 
 .. _module:ignore_users:
@@ -29,10 +29,11 @@ Events
 Client behaviour
 ----------------
 To ignore a user, effectively blocking them, the client should add the target
-user to the ``m.ignored_user_list`` event in their account data. Once ignored,
+user to the ``m.ignored_user_list`` event in their account data using 
-the client will no longer receive events sent by that user, with the exception
+|/user/<user_id>/account_data/<type>|_. Once ignored, the client will no longer 
-of state events. The client should either hide previous content sent by the
+receive events sent by that user, with the exception of state events. The client 
-newly ignored user or perform a new ``/sync`` with no previous token.
+should either hide previous content sent by the newly ignored user or perform 
+a new ``/sync`` with no previous token.
 
 Invites to new rooms by ignored users will not be sent to the client. The server
 may optionally reject the invite on behalf of the client.
@@ -48,12 +49,10 @@ To receive the events that were sent while the user was ignored the client
 should perform a fresh sync. The client may also un-hide any events it previously
 hid due to the user becoming ignored.
 
-Clients should be aware that split-brain 
-
 Server behaviour
 ----------------
 Following an update of the ``m.ignored_user_list``, the sync API for all clients
-will immediately start ignoring (or un-ignoring) the user. Clients are responsible
+should immediately start ignoring (or un-ignoring) the user. Clients are responsible
 for determining if they should hide previously sent events or to start a new sync
 stream.
 

specification/targets.yaml

@@ -61,6 +61,7 @@ groups:  # reusable blobs of files when prefixed with 'group:'
     - modules/event_context.rst
     - modules/cas_login.rst
     - modules/dm.rst
+    - modules/ignore_users.rst
 
 
 title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]