add api docs

pandora/annotation/views.py

@@ -162,8 +162,10 @@ def addAnnotation(request, data):
     }
     returns {
         id: string, // annotation id
-        ...
+        ... // more annotation properties
     }
+    see: addAnnotation, editAnnotation, findAnnotations, getAnnotation,
+    getTaskStatus, removeAnnotation
     '''
     for key in ('item', 'layer', 'in', 'out', 'value'):
         if key not in data:
@@ -213,13 +215,14 @@ def addAnnotations(request, data):
                 out: float, // out point in seconds
                 value: string // annotation value
             },
-            ...
+            ... // more annotations
         ]
     }
     returns {
-        taskId: string
+        taskId: string // task id, use `getTaskStatus` to poll
     }
-    FIXME: Explain what to do with task id
+    see: addAnnotation, editAnnotation, findAnnotations, getAnnotation,
+    getTaskStatus, removeAnnotation
     '''
     for key in ('item', 'layer', 'annotations'):
         if key not in data:

pandora/archive/views.py

@@ -323,6 +323,18 @@ def direct_upload(request):
 
 @login_required_json
 def taskStatus(request, data):
+    '''
+    Gets the status for a task
+    takes {
+        taskId: string // taskId
+    }
+    returns {
+        taskId: string, // taskId
+        status: string, // status, 'PENDING' or 'OK'
+        result: object // result data
+    }
+    note: To be deprecated, will be wrapped in regular API call
+    '''
     #FIXME: should check if user has permissions to get status
     if 'taskId' in data:
         task_id = data['taskId']

pandora/edit/views.py

@@ -30,24 +30,23 @@ def addClips(request, data):
     '''
     Adds one or more clips to an edit
     takes {
-        edit: string (edit id),
-        index: int (position, optional),
+        edit: string, // edit id,
+        index: integer, // position within edit (optional),
         clips: [
             {
-                item: string (item id),
-                in: float,
-                out: float,
+                item: string, // item id
+                in: float, // in point in seconds
+                out: float, // out point in seconds
             },
             {
-                annotation: string ("item_id/annotation_id")
+                annotation: string, // 'item_id/annotation_id'
             }
-            ...
+            ... // more clips
         ]
     }
     returns {}
-    Clips are either {item, in, out} or {annotation}. If index is missing,
-    clips will be inserted at the end of the edit.
-    FIXME: Does this really return nothing?
+    notes: Clips are either {item, in, out} or {annotation}. If index is
+    missing, clips will be inserted at the end of the edit.
     '''
     response = json_response()
     edit = get_edit_or_404_json(data['edit'])

pandora/item/views.py

@@ -531,13 +531,14 @@ def add(request, data):
     '''
     Adds a new item (without video)
     takes {
-        title: string, // optional
+        title: string, // item title (optional)
     }
     returns {
-        id: string,
-        title: string,
-        ...
+        id: string, // item id
+        title: string, // item title
+        ... // more item properties
     }
+    see: edit, find, get, remove, upload
     '''
     if not request.user.get_profile().capability('canAddItems'):
         response = json_response(status=403, text='permissino denied')