/dev/api: Fix docs for /api/v1/me/prefs

r2/r2/controllers/apiv1.py

@@ -73,7 +73,7 @@ class APIv1Controller(OAuth2ResourceController):
         return self.api_wrapper(resp)
 
     @require_oauth2_scope("identity")
-    @api_doc(api_section.account)
+    @api_doc(api_section.account, uri='/api/v1/me/prefs')
     @validate(
         fields=VList(
             "fields",
@@ -90,7 +90,8 @@ class APIv1Controller(OAuth2ResourceController):
                                           body=True)
 
     @require_oauth2_scope("account")
-    @api_doc(api_section.account, json_model=PREFS_JSON_VALIDATOR)
+    @api_doc(api_section.account, json_model=PREFS_JSON_VALIDATOR,
+             uri='/api/v1/me/prefs')
     @validate(validated_prefs=PREFS_JSON_VALIDATOR)
     def PATCH_prefs(self, validated_prefs):
         user_prefs = c.user.preferences()

r2/r2/lib/validator/validator.py

@@ -1786,6 +1786,21 @@ class VList(Validator):
                                code=400)
         return values
 
+    # Not i18n'able, but param_docs are not currently i18n'ed
+    NICE_SEP = {",": "comma"}
+    def param_docs(self):
+        if self.choices:
+            msg = ("A %(separator)s-separated list of items from "
+                   "this set:\n\n%(choices)s")
+            choices = "`" + "`  \n`".join(self.choices) + "`"
+        else:
+            msg = "A %(separator)s-separated list of items"
+            choices = None
+
+        sep = self.NICE_SEP.get(self.separator, self.separator)
+        docs = msg % {"separator": sep, "choices": choices}
+        return {self.param: docs}
+
 
 class VPriority(Validator):
     def run(self, val):

r2/r2/templates/apihelp.html

@@ -252,9 +252,13 @@ example, `t3_15bfi0`.
             <div class="info">
               ${unsafe(safemarkdown(docs.get('doc')))}
               <%
-                params = docs.get('parameters')
-                base_params = extends.get('parameters') if extends else None
                 json_model = docs.get('json_model')
+                if json_model:
+                  params = None
+                  base_params = None
+                else:
+                  params = docs.get('parameters')
+                  base_params = extends.get('parameters') if extends else None
               %>
               %if params or base_params or json_model:
                 <table class="parameters">
@@ -278,7 +282,7 @@ example, `t3_15bfi0`.
                 %endif
                 %if json_model:
                   <tr class="json-model">
-                    <th>${_("This endpoint expects JSON data using this model")}</th>
+                    <th>${_("This endpoint expects JSON data of this format")}</th>
                     <td>${unsafe(safemarkdown(json_model.docs_model(), wrap=False))}</td>
                   </tr>
                 %endif