start to improve API docs

pandora/annotation/views.py

@@ -112,15 +112,16 @@ actions.register(findAnnotations)
 @login_required_json
 def addAnnotation(request, data):
     '''
+    Adds a single annotation
     takes {
-            item: public_id,
-            layer: layerId,
+        item: string, (item id)
+        layer: string, (annotation layer id)
         in: float,
         out: float,
         value: string
     }
     returns {
-            id: string, //id of new annotation
+        id: string, (annotation id)
         ...
     }
     '''
@@ -152,18 +153,23 @@ actions.register(addAnnotation, cache=False)
 @login_required_json
 def addAnnotations(request, data):
     '''
+    Adds multiple annotations
     takes {
-            item: public_id,
-            layer: layerId,
-            annotations: [{
+        item: string (item id),
+        layer: string (annotation layer id), 
+        annotations: [
+            {
                 in: float,
                 out: float,
                 value: string
-            }, ...]
+            },
+            ...
+        ]
     }
     returns {
         taskId: string
     }
+    FIXME: Explain what to do with task id
     '''
     for key in ('item', 'layer', 'annotations'):
         if key not in data:

pandora/edit/views.py

@@ -27,20 +27,26 @@ def get_edit_or_404_json(id):
 @login_required_json
 def addClips(request, data):
     '''
+    Adds one or more clips to an edit
     takes {
-            edit: string,
-            index: int,
-            clips: []
-                item: string,
+        edit: string (edit id),
+        index: int (position, optional),
+        clips: [
+            {
+                item: string (item id),
                 in: float,
                 out: float,
-                annotation: string
+            },
+            {
+                annotation: string ("item_id/annotation_id")
             }
-        add clips with item/in/out or annotation to edit with id
-        clips are added at index or end if index is not provided
-        (annoation id is in the form item/annotation)
-        returns {
+            ...
+        ]
     }
+    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?
     '''
     response = json_response()
     edit = get_edit_or_404_json(data['edit'])

pandora/item/views.py

@@ -497,16 +497,16 @@ actions.register(get)
 @login_required_json
 def add(request, data):
     '''
+    Adds a new item (without video)
     takes {
-            title: string, //(optional)
+        title: string (optional)
     }
     returns {
-            id:
-            name:
+        id: string,
+        title: string,
         ...
     }
     '''
-
     if not request.user.get_profile().capability('canAddItems'):
         response = json_response(status=403, text='permissino denied')
     else: