api_docs: Improve captcha docs.

r2/r2/controllers/api.py

@@ -109,6 +109,16 @@ class ApiminimalController(MinimalController):
     @validatedForm()
     @api_doc(api_section.captcha)
     def POST_new_captcha(self, form, jquery, *a, **kw):
+        """
+        Responds with an `iden` of a new CAPTCHA
+
+        Use this endpoint if a user cannot read a given CAPTCHA,
+        and wishes to receive a new CAPTCHA.
+
+        To request the CAPTCHA image for an iden, use
+        [/captcha/`iden`](#GET_captcha_{iden}).
+        """
+
         iden = get_iden()
         jquery("body").captcha(iden)
         form._send_data(iden = iden) 

r2/r2/controllers/captcha.py

@@ -30,10 +30,21 @@ from r2.controllers.api_docs import api_doc, api_section
 class CaptchaController(RedditController):
     @api_doc(api_section.captcha, uri='/captcha/{iden}')
     def GET_captchaimg(self, iden):
-        """Request a captcha image given an iden.
+        """
+        Request a CAPTCHA image given an `iden`.
 
-        Responds with an image/png.
+        An iden is given as the `captcha` field with a `BAD_CAPTCHA`
+        error, you should use this endpoint if you get a
+        `BAD_CAPTCHA` error response.
 
+        Responds with a 120x50 `image/png` which should be displayed
+        to the user.
+
+        The user's response to the CAPTCHA should be sent as `captcha`
+        along with your request.
+
+        To request a new CAPTCHA,
+        use [/api/new_captcha](#POST_api_new_captcha).
         """
         image = captcha.get_image(iden)
         f = StringIO.StringIO()