update api docs

pandora/item/views.py

@@ -99,6 +99,44 @@ def parse_query(data, user):
 
 def find(request, data):
     '''
+    Finds items
+    takes {
+        clipsQuery: ...,
+        keys: [string], // list of keys to return (optional)
+        positions: [string], // list of item ids (optional)
+        query: { // query object
+            conditions: [{ // list of condition objects
+                key: string,
+                operator: string, // comparison operator, see below
+                value: string
+            }, { // or query objects (nested subconditions)
+                query: {
+                    conditions: [{}],
+                    operator: string
+                }
+            }],
+            operator: string // logical operator, '&' or '|'
+        },
+        sort: [{ // list of sort objects
+            key: string, // item key
+            operator: string // sort order, '+' or '-'
+        }],
+        range: [int, int] // from, to
+    }
+    returns {
+        items: [{
+            id: string, // item id
+            ...
+        }]
+    } or { // if `keys` is missing
+        items: int // total number of items
+    } or { // if `positions` is set
+        ...
+    }
+    Comparison operators are '=' (contains) '==' (is), '^' (starts with),
+    '$' (ends with), '<', '<=', '>', or '>=', each optionally prefixed with '!'
+    (not).
+
         Example: 
             find({
                 query:{
@@ -110,13 +148,6 @@ def find(request, data):
                 sort: [{key: 'title', operator: '+'}]
             })
 
-        takes {
-            'query': query,
-            'sort': array,
-            'range': array
-            clipsQuery: ...
-        }
-
             query: query object, more on query syntax at
                    https://wiki.0x2620.org/wiki/pandora/QuerySyntax
             sort: array of key, operator dics
@@ -397,6 +428,7 @@ actions.register(findId)
 
 def getMetadata(request, data):
     '''
+    Gets metadata from an external service
     takes {
         id: string,
         keys: [string]
@@ -406,7 +438,6 @@ def getMetadata(request, data):
        key: value
        ..
     }
-
     '''
     response = json_response({})
     if settings.DATA_SERVICE: