start to improve API docs

pandora/annotation/views.py

@@ -112,17 +112,18 @@ actions.register(findAnnotations)
 @login_required_json
 def addAnnotation(request, data):
     '''
-        takes {
+    Adds a single annotation
-            item: public_id,
+    takes {
-            layer: layerId,
+        item: string, (item id)
-            in: float,
+        layer: string, (annotation layer id)
-            out: float,
+        in: float,
-            value: string
+        out: float,
-        }
+        value: string
-        returns {
+    }
-            id: string, //id of new annotation
+    returns {
-            ...
+        id: string, (annotation id)
-        }
+        ...
+    }
     '''
     for key in ('item', 'layer', 'in', 'out', 'value'):
         if key not in data:
@@ -152,18 +153,23 @@ actions.register(addAnnotation, cache=False)
 @login_required_json
 def addAnnotations(request, data):
     '''
-        takes {
+    Adds multiple annotations
-            item: public_id,
+    takes {
-            layer: layerId,
+        item: string (item id),
-            annotations: [{
+        layer: string (annotation layer id), 
+        annotations: [
+            {
                 in: float,
                 out: float,
                 value: string
-            }, ...]
+            },
-        }
+            ...
-        returns {
+        ]
-            taskId: 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):
     '''
-        takes {
+    Adds one or more clips to an edit
-            edit: string,
+    takes {
-            index: int,
+        edit: string (edit id),
-            clips: []
+        index: int (position, optional),
-                item: string,
+        clips: [
+            {
+                item: string (item id),
                 in: float,
                 out: float,
-                annotation: string
+            },
-        }
+            {
-        add clips with item/in/out or annotation to edit with id
+                annotation: string ("item_id/annotation_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):
     '''
-        takes {
+    Adds a new item (without video)
-            title: string, //(optional)
+    takes {
-        }
+        title: string (optional)
-        returns {
+    }
-            id:
+    returns {
-            name:
+        id: string,
-            ...
+        title: string,
-        }
+        ...
+    }
     '''
-
     if not request.user.get_profile().capability('canAddItems'):
         response = json_response(status=403, text='permissino denied')
     else: