From ba6ce165094a2f82e757505fc71cac902b01153c Mon Sep 17 00:00:00 2001
From: Kegan Dougal <kegan@matrix.org>
Date: Mon, 1 Jun 2015 14:34:13 +0100
Subject: [PATCH] Modify how descriptions are shown. Add profile API
 descriptions.

---
 api/client-server/v1/profile.yaml                   | 6 ++++++
 templating/matrix_templates/templates/http-api.tmpl | 2 ++
 templating/matrix_templates/units.py                | 2 +-
 3 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/api/client-server/v1/profile.yaml b/api/client-server/v1/profile.yaml
index a6d16d41..ff25cae1 100644
--- a/api/client-server/v1/profile.yaml
+++ b/api/client-server/v1/profile.yaml
@@ -21,6 +21,9 @@ paths:
   "/profile/{userId}/displayname":
     put:
       summary: Set the user's display name.
+      description: |-
+        This API sets the given user's display name. You must have permission to
+        set this user's display name, e.g. you need to have their ``access_token``.
       security:
         - accessToken: []
       parameters:
@@ -84,6 +87,9 @@ paths:
   "/profile/{userId}/avatar_url":
     put:
       summary: Set the user's avatar URL.
+      description: |-
+        This API sets the given user's avatar URL. You must have permission to
+        set this user's avatar URL, e.g. you need to have their ``access_token``.
       security:
         - accessToken: []
       parameters:
diff --git a/templating/matrix_templates/templates/http-api.tmpl b/templating/matrix_templates/templates/http-api.tmpl
index 858ae534..b8dcace5 100644
--- a/templating/matrix_templates/templates/http-api.tmpl
+++ b/templating/matrix_templates/templates/http-api.tmpl
@@ -2,8 +2,10 @@
 {{(5 + (endpoint.path | length) + (endpoint.method | length)) * title_kind}}
 
 {{endpoint.desc | wrap(80)}}
+
 {{":Rate-limited: Yes." if endpoint.rate_limited else "" }}
 {{":Requires auth: Yes." if endpoint.requires_auth else "" }}
+
 Request format:
 
 ================== ================= =========== ===============================
diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py
index 65c67d13..4dcd0c33 100644
--- a/templating/matrix_templates/units.py
+++ b/templating/matrix_templates/units.py
@@ -106,7 +106,7 @@ class MatrixUnits(Units):
                 single_api = api["paths"][path][method]
                 endpoint = {
                     "title": single_api.get("summary", ""),
-                    "desc": single_api.get("description", ""),
+                    "desc": single_api.get("description", single_api.get("summary", "")),
                     "method": method.upper(),
                     "path": path,
                     "requires_auth": "security" in single_api,