api docs: Document the PATCH /api/v1/messages/<msg_id> endpoint.

Note that there is no JavaScript equivalent for requesting this
endpoint in zulip-js yet.

templates/zerver/api/arguments.json

@@ -180,5 +180,32 @@
             "required":"Optional",
             "example":"1375801870:2942"
         }
+    ],
+    "update-message.md":[
+        {
+            "argument":"message_id",
+            "description":"The ID of the message that you wish to edit/update.",
+            "required":"Required",
+            "example":"134"
+        },
+        {
+            "argument":"subject",
+            "description":"The topic of the message. Only required for a stream message. Defaults to `None`. Maximum length of 60 characters.",
+            "required":"Optional",
+            "example":"Castle"
+        },
+        {
+            "argument":"content",
+            "description":"The content of the message. Maximum message size of 10000 bytes.",
+            "required":"Optional",
+            "example":"Hello"
+        },
+        {
+            "argument":"propagate_mode",
+            "description":"In the case of a topic update, `propagate_mode` is a value specifying whether the topic of any other messages in the same conversation would be updated or not. Possible values include: <br/> <br/> * **change_one** (Default): Update the topic only of the message with the given `message_id`. <br/> * **change_all**: Update the topic of all messages with the same previous topic as the message with `message_id`. <br/> * **change_later**: Update the topic of the message with `message_id` *and* update the topic of the messages with the same previous topic after it.",
+            "required":"Optional",
+            "example":"change_all"
+        }
+
     ]
 }

templates/zerver/api/sidebar.md

@@ -8,6 +8,7 @@
 * [Stream message](/api/stream-message)
 * [Private message](/api/private-message)
 * [Render message](/api/render-message)
+* [Update a message](/api/update-message)
 
 #### Streams
 

templates/zerver/api/update-message.md

@@ -0,0 +1,85 @@
+# Update a message
+
+Edit/update the content or topic of a message.
+
+`PATCH {{ api_url }}/v1/messages/<msg_id>`
+
+`<msg_id>` in the above URL should be replaced with the ID of the
+message you wish you update.
+
+## Permissions
+
+You only have permission to edit a message if:
+
+1. You sent it, **OR**:
+2. This is a topic-only edit for a (no topic) message, **OR**:
+3. This is a topic-only edit and you are an admin.
+
+## Arguments
+
+{generate_api_arguments_table|arguments.json|update-message.md}
+
+## Usage examples
+<div class="code-section" markdown="1">
+<ul class="nav">
+<li data-language="curl">curl</li>
+<li data-language="python">Python</li>
+</ul>
+<div class="blocks">
+
+<div data-language="curl" markdown="1">
+
+```
+curl -X "PATCH" {{ api_url }}/v1/messages/<msg_id> \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
+    -d "content=New content"
+```
+</div>
+
+<div data-language="python" markdown="1">
+```python
+#!/usr/bin/env python
+
+import zulip
+
+# Download ~/zuliprc-dev from your dev server
+client = zulip.Client(config_file="~/zuliprc-dev")
+
+# Edit a message
+print(client.update_message({
+    "message_id": 131,
+    "content": "New content"
+}))
+
+```
+</div>
+
+</div>
+
+</div>
+
+## Response
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+```
+{
+    'msg':'',
+    'result':'success'
+}
+```
+
+A typical JSON response for when one doesn't have the permission to
+edit a particular message:
+
+```
+{
+    'code':'BAD_REQUEST',
+    'result':'error',
+    'msg':"You don't have permission to edit this message"
+}
+```
+
+{!invalid-api-key-json-response.md!}

zerver/tests/test_docs.py

@@ -64,6 +64,7 @@ class DocPageTest(ZulipTestCase):
         self._test('/api/register-queue', 'apply_markdown')
         self._test('/api/get-events-from-queue', 'dont_block')
         self._test('/api/delete-queue', 'Delete a previously registered queue')
+        self._test('/api/update-message', 'propagate_mode')
         self._test('/team/', 'industry veterans')
         self._test('/history/', 'Cambridge, Massachusetts')
         # Test the i18n version of one of these pages.