Modify how descriptions are shown. Add profile API descriptions.

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:

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:
 
 ================== ================= =========== ===============================

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,