update api docs

pandora/annotation/views.py

@@ -73,21 +73,32 @@ def findAnnotations(request, data):
     '''
     takes {
         query: {
-                conditions: [],
-                operator: '&'
+            conditions: [{
+                key: string,
+                operator: string,
+                value: string
+            }],
+            operator: string // '&' or '|'
         },
         itemsQuery: {
-                conditions: [],
-                operator: '&'
+            conditions: [{
+                key: string,
+                operator: string,
+                value: string
+            }],
+            operator: string // '&' or '|'
         },
         keys: [],
         position: int,
         positions: [],
-            range: [in, out],
+        range: [int, int],
         sort: []
     }
     returns {
-            annotations = [{..}, {...}, ...]
+        annotations: [{
+            id: string,
+            ...
+        }]
     }
     '''
     response = json_response()
@@ -118,12 +129,14 @@ actions.register(findAnnotations)
 
 def getAnnotation(request, data):
     '''
+    Gets data for an annotation
     takes {
-            id: string,
-            keys: [string]
+        id: string, // annotation id
+        keys: [string] // list of keys to return
     }
     returns {
-            key: value
+        key: value,
+        ...
     }
     '''
     response = json_response({})
@@ -218,11 +231,13 @@ actions.register(addAnnotations, cache=False)
 @login_required_json
 def removeAnnotation(request, data):
     '''
+    Removes an annotation
     takes {
-            id: annotationId
+        id: string // annotation id
     }
     returns {
     }
+    FIXME: returns nothing?
     '''
     response = json_response({})
     a = get_object_or_404_json(models.Annotation, public_id=data['id'])
@@ -238,14 +253,15 @@ actions.register(removeAnnotation, cache=False)
 @login_required_json
 def editAnnotation(request, data):
     '''
+    Edits an annotation
     takes {
-            id:,
-            in: float,
-            out: float,
-            value: string,
+        id: string, // annotation id
+        in: float, // in point in seconds, optional
+        out: float, // out point in seconds, optional
+        value: string // annotation value, optional
     }
     returns {
-            id:
+        id: string, // annotation id
         ...
     }
     '''