From 6da0017152bfdc458f398b1c118c19ec698007a5 Mon Sep 17 00:00:00 2001
From: Andre D <andre@andred.ca>
Date: Wed, 12 Jun 2013 10:06:00 -0700
Subject: [PATCH] api_docs: Improve captcha docs.

---
 r2/r2/controllers/api.py     | 10 ++++++++++
 r2/r2/controllers/captcha.py | 15 +++++++++++++--
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/r2/r2/controllers/api.py b/r2/r2/controllers/api.py
index 7d5dc23fb..c8782fe4d 100755
--- a/r2/r2/controllers/api.py
+++ b/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) 
diff --git a/r2/r2/controllers/captcha.py b/r2/r2/controllers/captcha.py
index baa21f183..65366cd20 100644
--- a/r2/r2/controllers/captcha.py
+++ b/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()