From 3950213960d43f2dc2bf5c70f062d615129ad3a6 Mon Sep 17 00:00:00 2001
From: rolux <rolux@rolux.org>
Date: Fri, 19 Dec 2014 15:31:57 +0000
Subject: [PATCH] update api docs

---
 pandora/archive/views.py  | 11 +++++++---
 pandora/document/views.py |  2 +-
 pandora/edit/views.py     | 10 ++++-----
 pandora/entity/views.py   | 17 +++++++--------
 pandora/item/views.py     |  2 +-
 pandora/itemlist/views.py | 11 +++++-----
 pandora/person/views.py   |  2 +-
 pandora/sequence/views.py | 46 ++++++++++++++++++++-------------------
 pandora/text/views.py     |  5 +++--
 pandora/tv/views.py       | 19 ++++++++--------
 pandora/user/views.py     |  3 ++-
 11 files changed, 69 insertions(+), 59 deletions(-)

diff --git a/pandora/archive/views.py b/pandora/archive/views.py
index f0b5589c6..697dd2a84 100644
--- a/pandora/archive/views.py
+++ b/pandora/archive/views.py
@@ -29,6 +29,11 @@ from chunk import process_chunk
 
 @login_required_json
 def removeVolume(request, data):
+    '''
+    Removes a volume
+    takes {} // undocumented
+    returns {} // undocumented
+    '''
     user = request.user
     try:
         volume = models.Volume.objects.get(user=user, name=data['volume'])
@@ -352,10 +357,10 @@ actions.register(taskStatus, cache=False)
 @login_required_json
 def moveMedia(request, data):
     '''
-    Move media files from one item to another
+    Moves one or more media files from one item to another
     takes {
-        ids: ids of files
-        item: new public_id
+        ids: [string], // list of file ids
+        item: id // target item id
     }
     returns {}
     notes: This will *not* (yet) shift the corresponding annotations.
diff --git a/pandora/document/views.py b/pandora/document/views.py
index b629b57e3..0a912011b 100644
--- a/pandora/document/views.py
+++ b/pandora/document/views.py
@@ -250,7 +250,7 @@ def sortDocuments(request, data):
     Sets the sort order for the documents related to a given item
     takes {
         item: string, // item id
-        ids: [string] // list of document ids
+        ids: [string] // ordered list of document ids
     }
     returns {}
     see: addDocument, editDocument, findDocument, removeDocument, sortDocuments
diff --git a/pandora/edit/views.py b/pandora/edit/views.py
index 38a283414..1e2464a98 100644
--- a/pandora/edit/views.py
+++ b/pandora/edit/views.py
@@ -141,13 +141,12 @@ actions.register(editClip, cache=False)
 @login_required_json
 def orderClips(request, data):
     '''
-    Updates manual ordering of clips within an edit
+    Sets the manual ordering of clips within a given edit
     takes {
         edit: string, // edit id
         ids: [string] // clip ids in new order
     }
-    returns {
-    }
+    returns {}
     see: addClips, editClip, removeClip, sortClips
     '''
     edit = get_edit_or_404_json(data['edit'])
@@ -207,7 +206,7 @@ def sortClips(request, data):
         sort: object // sort
     }
     returns {}
-    note: sort is [{key: string, operator: string}], operator can be '+' or '-'
+    notes: sort is [{key: string, operator: string}], operator can be '+' or '-'
     see: addClips, editClip, orderClips, removeClips
     '''
     edit = get_edit_or_404_json(data['edit'])
@@ -486,7 +485,8 @@ def sortEdits(request, data):
         ids: [string] // ordered list of edit ids
     }
     returns {}
-    notes: Sorting featured edits requires a specific per-user capability
+    notes: Setting the order of featured edits requires the appropriate
+    capability.
     see: addEdit, editEdits, findEdits, getEdit, removeEdit
     '''
     position = 0
diff --git a/pandora/entity/views.py b/pandora/entity/views.py
index 9d3266e0f..93ca52eea 100644
--- a/pandora/entity/views.py
+++ b/pandora/entity/views.py
@@ -240,11 +240,12 @@ def getEntity(request, data):
     '''
     Gets an entity by id
     takes {
-        id: string,
-        keys: [string]
+        id: string, // entity id
+        keys: [string] // list of properties to return
     }
     returns {
-        key: value
+        key: value, // property id and value
+        ... // more key/value pairs
     }
     see: addEntity, editEntity, findEntities, removeEntity
     '''
@@ -258,14 +259,12 @@ actions.register(getEntity)
 @login_required_json
 def removeEntity(request, data):
     '''
-    Removes an entity
+    Removes one or more entities
     takes {
-        id: string,
-        or
-        ids: [string]
-    }
-    returns {
+        id: string, // either entity id
+        ids: [string] // or list of entity ids
     }
+    returns {}
     see: addEntity, editEntity, findEntities, getEntity
     '''
     response = json_response()
diff --git a/pandora/item/views.py b/pandora/item/views.py
index f5fe0f6a1..09c756ca0 100644
--- a/pandora/item/views.py
+++ b/pandora/item/views.py
@@ -582,7 +582,7 @@ def remove(request, data):
         id: string // item id
     }
     returns {}
-    notes: The return status is 200 for success or 403 for permission denied.
+    notes: The return status code is 200 for success or 403 for permission denied.
     see: add, edit, find, get, lookup, upload
     '''
     response = json_response({})
diff --git a/pandora/itemlist/views.py b/pandora/itemlist/views.py
index 753a3eb4f..011c145f9 100644
--- a/pandora/itemlist/views.py
+++ b/pandora/itemlist/views.py
@@ -110,12 +110,12 @@ def getList(request, data):
     '''
     Gets a list by id
     takes {
-        id: listid
+        id: string // list id
     }
     returns {
-        id:
-        section:
-        ...
+        id: string, // list id
+        section: string, // lists section (like 'personal')
+        ... // more key/value pairs
     }
     see: addList, editList, findLists, removeList, sortLists
     '''
@@ -374,7 +374,7 @@ actions.register(unsubscribeFromList, cache=False)
 @login_required_json
 def sortLists(request, data):
     '''
-    Set order of lists
+    Sets the order of lists in a given section
     takes {
         section: string, // lists section
         ids: [string] // ordered list of lists
@@ -382,6 +382,7 @@ def sortLists(request, data):
     returns {}
     notes: Possible sections are 'personal', 'favorite' and 'featured'. Setting
     the order of featured lists requires the appropriate capability.
+    see: addList, editList, findLists, getList, removeList
     '''
     position = 0
     section = data['section']
diff --git a/pandora/person/views.py b/pandora/person/views.py
index 290f9ff75..fb6081f97 100644
--- a/pandora/person/views.py
+++ b/pandora/person/views.py
@@ -54,7 +54,7 @@ def sortName(request, data):
         name: sortName, // sort name for this name
         ... // more results
     }
-    see editName, findNames
+    see: editName, findNames
     '''
     names = data.get('names', [])
     if 'name' in data:
diff --git a/pandora/sequence/views.py b/pandora/sequence/views.py
index 51907fb4f..786091582 100644
--- a/pandora/sequence/views.py
+++ b/pandora/sequence/views.py
@@ -51,16 +51,17 @@ def order_query(qs, sort):
 
 def findSequences(request, data):
     '''
-        takes {
-            query: ...
-            itemsQuery: ...
-        }
-
-        one of your conditions has to be key: 'mode', value: [shape,color], operator: '=='
-
-        returns {
-            items: [object]
-        }
+    Finds sequences for a given query
+    takes {
+        query: object // query object, see `find`
+        itemsQuery: object // limit to matching items, query object, see `find`
+    }
+    returns {
+        items: [object] // list of sequences
+    }
+    notes: One of the query conditions has to be {key: 'mode', operator: '==',
+    value: 'color' or 'shape'}.
+    see: find, getSequence
     '''
     response = json_response()
 
@@ -93,18 +94,19 @@ actions.register(findSequences)
 
 def getSequence(request, data):
     '''
-        takes {
-            id
-            mode 
-            position
-        }
-
-        returns {
-            id
-            mode
-            in
-            out
-        }
+    Gets a sequence by id
+    takes {
+        id: string, // sequence id
+        mode: string, // sequence mode ('color' or 'shape')
+        position: int // position in seconds
+    }
+    returns {
+        id: string, // sequence id
+        mode: string, // sequence mode ('color' or 'shape')
+        in: int, // in point in seconds
+        out: int // out point in seconds
+    }
+    see: findSequences
     '''
     response = json_response()
     position = float('%0.03f' % data['position'])
diff --git a/pandora/text/views.py b/pandora/text/views.py
index 3d7be7272..aabf00fab 100644
--- a/pandora/text/views.py
+++ b/pandora/text/views.py
@@ -202,7 +202,7 @@ def findTexts(request, data):
     }
     notes: Possible query keys are 'featured', 'name', 'subscribed' and 'user',
     possible keys are 'featured', 'name', 'query', 'subscribed' and 'user'.
-    see: addText, editText, getText, removeText, sortTexts
+    see: addText, editText, find, getText, removeText, sortTexts
     '''
     query = parse_query(data, request.user)
 
@@ -317,7 +317,8 @@ def sortTexts(request, data):
         ids: [string] // ordered list of text ids
     }
     returns {}
-    notes: Sorting featured texts requires the appropriate capability.
+    notes: Setting the order of featured texts requires the appropriate
+    capability.
     see: addText, findTexts, getText, editText, removeText
     '''
     position = 0
diff --git a/pandora/tv/views.py b/pandora/tv/views.py
index 0e745a9be..06d79820f 100644
--- a/pandora/tv/views.py
+++ b/pandora/tv/views.py
@@ -11,15 +11,16 @@ from ox.django.api import actions
 
 def tv(request, data):
     '''
-        takes {
-            list: string
-        }
-        returns {
-            item: string,
-            position: float,
-            title: string,
-            ...
-        }
+    Gets TV program for a given list
+    takes {
+        list: string // list name
+    }
+    returns {
+        item: string, // current item
+        position: float, // current position in seconds
+        title: string, // item title
+        ... // more item properties
+    }
     '''
     if 'list' in data and data['list']:
         list = get_list_or_404_json(data['list'])
diff --git a/pandora/user/views.py b/pandora/user/views.py
index 345f1224c..30a35508d 100644
--- a/pandora/user/views.py
+++ b/pandora/user/views.py
@@ -495,7 +495,7 @@ def findUsers(request, data):
     }
     notes: Possible query keys are 'browser', 'email', 'groups', 'lastLogin'
     and 'username'.
-    see: editUser, findUser, getUser, removeUser
+    see: editUser, find, findUser, getUser, removeUser
     '''
     response = json_response(status=200, text='ok')
     query = parse_query(data, request.user)
@@ -550,6 +550,7 @@ actions.register(getUser)
 @login_required_json
 def mail(request, data):
     '''
+    Sends mail to a list of users
     takes {
         to: [string], // list of usernames of recipients
         subject: string, // subject