Document how to report content

Fixes: https://github.com/matrix-org/matrix-doc/issues/739

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

api/client-server/report_content.yaml

@@ -0,0 +1,78 @@
+# Copyright 2018 Travis Ralston
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Report Content API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/rooms/{roomId}/report/{eventId}":
+    post:
+      summary: Reports an event as inappropriate.
+      description: |-
+        Reports an event as inappropriate to the server, which may then notify
+        the appropriate people.
+      operationId: reportContent
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room in which the event being reported is located.
+          required: true
+          x-example: "!637q39766251:example.com"
+        - in: path
+          type: string
+          name: eventId
+          description: The event to report.
+          required: true
+          x-example: "$something:domain.com"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: {
+              "score": -100,
+              "reason": "this makes me sad"
+            }
+            required: ['score', 'reason']
+            properties:
+              score:
+                type: integer
+                description: |-
+                  The score to rate this content as where -100 is most offensive
+                  and 0 is inoffensive.
+              reason:
+                type: string
+                description: The reason the content is being reported. May be blank.
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: The event has been reported successfully.
+          schema:
+            type: object
+          examples:
+            application/json: {}
+      tags:
+        - Reporting content

specification/modules/report_content.rst

@@ -0,0 +1,35 @@
+.. Copyright 2018 Travis Ralston
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+..     http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+Reporting Content
+=================
+
+.. _module:report_content:
+
+Users may encounter content which they find inappropriate and should be able
+to report it to the server administrators or room moderators for review. This
+module defines a way for users to report content.
+
+Content is reported based upon a negative score, where -100 is "most offensive"
+and 0 is "inoffensive".
+
+Client behaviour
+----------------
+{{report_content_cs_http_api}}
+
+Server behaviour
+----------------
+Servers are free to handle the reported content however they desire. This may
+be a dedicated room to alert server administrators to the reported content or
+some other mechanism for notifying the appropriate people.

specification/targets.yaml

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