apidoc for "new comment"

isso/views/comments.py

@@ -60,6 +60,12 @@ def xhr(func):
     not forged (XHR is restricted by CORS separately).
     """
 
+
+	"""
+	@apiDefine csrf
+	@apiHeader {string="application/json"} Content-Type
+		The content type must be set to `application/json` to prevent CSRF attacks.
+	"""
     def dec(self, env, req, *args, **kwargs):
 
         if req.content_type and not req.content_type.startswith("application/json"):
@@ -140,6 +146,64 @@ class API(object):
 
         return True, ""
 
+    """
+    @api {post} /new create new
+    @apiGroup Comment
+	@apiUse csrf
+
+    @apiParam {string} uri
+        The uri of the thread to create the comment on.
+    @apiParam {string} text
+        The comment’s raw text.
+    @apiParam {string} [author]
+        The comment’s author’s name.
+    @apiParam {string} [email]
+        The comment’s author’s email address.
+    @apiParam {string} [website]
+        The comment’s author’s website’s url.
+    @apiParam {number} [parent]
+        The parent comment’s id iff the new comment is a response to an existing comment.
+
+	@apiExample {curl} Create a reply to comment with id 15:
+		curl 'https://comments.example.com/new?uri=/thread/' -d '{"text": "Stop saying that! *isso*!", "author": "Max Rant", "email": "rant@example.com", "parent": 15}' -H 'Content-Type: application/json'
+
+	@apiSuccess {number} id
+		The comment’s id (assigned by the server).
+	@apiSuccess {number} parent
+		Id of the comment this comment is a reply to. `null` if this is a top-level-comment.
+	@apiSuccess {number=1,2,4} mode
+		The comment’s mode:
+		value | explanation
+		 ---  | ---
+		 `1`  | accepted: The comment was accepted by the server and is published.
+		 `2`  | in moderation queue: The comment was accepted by the server but awaits moderation.
+		 `4`  | deleted, but referenced: The comment was deleted on the server but is still referenced by replies.
+	@apiSuccess {string} author
+		The comments’s author’s name or `null`.
+	@apiSuccess {string} website
+		The comment’s author’s website or `null`.
+	@apiSuccess {string} hash
+		A hash uniquely identifying the comment’s author.
+	@apiSuccess {number} created
+		UNIX timestamp of the time the comment was created (on the server).
+	@apiSuccess {number} modified
+		UNIX timestamp of the time the comment was last modified (on the server). `null` if the comment was not yet modified.
+
+	@apiSuccessExample Success after the above request:
+	    {
+			"website": null,
+			"author": "Max Rant",
+			"parent": 15,
+			"created": 1464940838.254393,
+			"text": "<p>Stop saying that! <em>isso</em>!</p>",
+			"dislikes": 0,
+			"modified": null,
+			"mode": 1,
+			"hash": "e644f6ee43c0",
+			"id": 10,
+			"likes": 0
+		}
+    """
     @xhr
     @requires(str, 'uri')
     def new(self, environ, request, uri):