/dev/api: Put /api/store_visits in the API docs

api_doc notes' plumbing was changed slightly so
that VGold() endpoints automatically state that
they require a gold subscription in the docs.

"save" OAuth2 scope added to the store_visits endpoint.

r2/r2/controllers/api.py

@@ -3926,10 +3926,12 @@ class ApiController(RedditController):
         c.user.pref_public_server_seconds = seconds_visibility == "public"
         c.user._commit()
 
+    @require_oauth2_scope("save")
     @noresponse(VGold(),
                 VModhash(),
                 links = VByName('links', thing_cls=Link, multiple=True,
                                 limit=100))
+    @api_doc(api_section.links_and_comments)
     def POST_store_visits(self, links):
         if not c.user.pref_store_visits or not links:
             return

r2/r2/controllers/api_docs.py

@@ -145,6 +145,7 @@ class ApidocsController(RedditController):
                 # append a message to the docstring if supplied
                 notes = docs.get("notes")
                 if notes:
+                    notes = "\n".join(notes)
                     if docs["doc"]:
                         docs["doc"] += "\n\n" + notes
                     else:

r2/r2/controllers/listingcontroller.py

@@ -201,7 +201,7 @@ listing_api_doc = partial(
     api_doc,
     section=api_section.listings,
     extends=ListingController.GET_listing,
-    notes=paginated_listing.doc_note,
+    notes=[paginated_listing.doc_note],
     extensions=["json", "xml"],
 )
 

r2/r2/controllers/reddit_base.py

@@ -641,7 +641,9 @@ def paginated_listing(default_page_size=25, max_page_size=100, backend='sql'):
             return fn(self, **kw)
 
         if hasattr(fn, "_api_doc"):
-            fn._api_doc["notes"] = paginated_listing.doc_note
+            notes = fn._api_doc["notes"] or []
+            notes.append(paginated_listing.doc_note)
+            fn._api_doc["notes"] = notes
 
         return new_fn
     return decorator

r2/r2/lib/validator/validator.py

@@ -76,6 +76,7 @@ def can_comment_link(article):
             visible_promo(article))
 
 class Validator(object):
+    notes = None
     default_param = None
     def __init__(self, param=None, default=None, post=True, get=True, url=True,
                  body=False, docs=None):
@@ -166,14 +167,18 @@ def _make_validated_kw(fn, simple_vals, param_vals, env):
 def set_api_docs(fn, simple_vals, param_vals, extra_vals=None):
     doc = fn._api_doc = getattr(fn, '_api_doc', {})
     param_info = doc.get('parameters', {})
+    notes = doc.get('notes', [])
     for validator in chain(simple_vals, param_vals.itervalues()):
         param_docs = validator.param_docs()
         if validator.docs:
             param_docs.update(validator.docs)
         param_info.update(param_docs)
+        if validator.notes:
+            notes.append(validator.notes)
     if extra_vals:
         param_info.update(extra_vals)
     doc['parameters'] = param_info
+    doc['notes'] = notes
 
 
 def validate(*simple_vals, **param_vals):
@@ -854,9 +859,15 @@ class VByName(Validator):
 
     def param_docs(self):
         thingtype = (self.thing_cls or Thing).__name__.lower()
-        return {
-            self.param: "[fullname](#fullnames) of a %s" % thingtype,
-        }
+        if self.multiple:
+            return {
+                self.param: ("A comma-separated list of %s [fullnames]"
+                             "(#fullnames)" % thingtype)
+            }
+        else:
+            return {
+                self.param: "[fullname](#fullnames) of a %s" % thingtype,
+            }
 
 class VByNameIfAuthor(VByName):
     def run(self, fullname):
@@ -958,6 +969,7 @@ class VVerifiedUser(VUser):
             raise VerifiedUserRequiredException
 
 class VGold(VUser):
+    notes = "*Requires a subscription to [reddit gold](/gold/about)*"
     def run(self):
         VUser.run(self)
         if not c.user.gold: