update api docs

pandora/annotation/views.py

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