update api docs

pandora/annotation/views.py

@@ -90,7 +90,7 @@ def findAnnotations(request, data):
             ... // more annotation properties
         }]
     }
-    see: addAnnotation, addAnnotations, editAnnotation, getAnnotation,
+    see: addAnnotation, addAnnotations, editAnnotation, find, getAnnotation,
     removeAnnotation
     '''
     response = json_response()

pandora/app/views.py

@@ -96,13 +96,15 @@ def robots_txt(request, url):
 
 def getPage(request, data):
     '''
+    Gets the text/html for a given site page (like 'About')
     takes {
-            name: pagename
+        name: string // page id
     }
     returns {
-            name:
+        name: string, // page id
-            text:
+        text: string // text/html
     }
+    see: editPage
     '''
     if isinstance(data, basestring):
         name = data
@@ -120,14 +122,16 @@ actions.register(getPage)
 @login_required_json
 def editPage(request, data):
     '''
+    Edits a site page (like 'About')
     takes {
-            name: pagename
+        name: string, // page id
-            text: text
+        text: string // new text/html
     }
     returns {
-            name:
+        name: string, // page id
-            text:
+        text: string // new text/html
     }
+    see: getPage
     '''
     if request.user.get_profile().capability('canEditSitePages'):
         page, created = models.Page.objects.get_or_create(name=data['name'])
@@ -143,9 +147,11 @@ actions.register(editPage)
 
 def init(request, data):
     '''
+    Makes an init request
     takes {}
     returns {
-            user: object
+        site: object, // site data
+        user: object // user data
     }
     '''
     response = json_response({})
@@ -162,16 +168,16 @@ actions.register(init)
 
 def embedURL(request, data):
     '''
-        
+    Returns HTML to embed a given URL
     takes {
-            url
+        url: string, // URL
-            maxwidth
+        maxwidth: int, // max width in px
-            maxheight
+        maxheight: int // max height in px
     }
     returns {
-            html
+        html: string // HTML
-            ...
     }
+    see: getEmbedDefaults
     '''
     response = json_response({})
     response['data'] = ox.get_embed_code(data['url'], data.get('maxwidth'), data.get('maxheight'))
@@ -180,19 +186,21 @@ actions.register(embedURL)
 
 def getEmbedDefaults(request, data):
     '''
+    Returns embed default values
     takes {}
     returns {
-        document: str // first document, sorted by id
+        document: string, // first document, sorted by id
-        edit: str // first edit, sorted by name
+        edit: string, // first edit, sorted by name
-        editDuration: float // duration of that edit
+        editDuration: float, // duration of that edit
-        item: str // first item, sorted by id
+        item: string, // first item, sorted by id
         itemDuration: float // duration of that item
         itemRatio: float // video ratio of that item
-        list: str // first list, sorted by name
+        list: string // first list, sorted by name
-        text: str // first text, sorted by name
+        text: string // first text, sorted by name
         videoRatio: float // pandora.site.video.previewRatio
         videoResolution: int // largest value in pandora.site.video.resolutions
     }
+    see: embedURL
     '''
     from document.models import Document
     from item.models import Item

pandora/archive/views.py

@@ -169,7 +169,7 @@ def addMedia(request, data):
     returns {
         item: id // item id
     }
-    see: editMedia, moveMedia, removeMedia
+    see: editMedia, findMedia, moveMedia, removeMedia
     '''
     response = json_response({})
     oshash = data.pop('id')
@@ -399,7 +399,7 @@ actions.register(moveMedia, cache=False)
 @login_required_json
 def editMedia(request, data):
     '''
-    Edits one or more media files
+    Edits data for one or more media files
     takes {
         files: [
             {
@@ -550,7 +550,7 @@ def findMedia(request, data):
     returns {
         items: [object] // list of items
     }
-    see: addMedia, editMedia, moveMedia, removeMedia
+    see: addMedia, editMedia, find, moveMedia, removeMedia
     '''
     if not data.get('sort'):
         data['sort'] = [{'key': 'path', 'operator': '+'}]

pandora/changelog/views.py

@@ -42,25 +42,17 @@ def order_query(qs, sort):
 @capability_required_json('canManageUsers')
 def findChangeLogs(request, data):
     '''
+    Finds changelog entries for a given query
     takes {
-            query: {
+        query: object, // query object, see `find`
-                conditions: [
+        sort: [object], // list of sort objects, see `find`
-                    {
+        range: [int, int], // range of results to return
-                        key: 'user',
+        keys: [string] // list of properties to return
-                        value: 'something',
-                        operator: '='
-                    }
-                ]
-                operator: ","
-            },
-            sort: [{key: 'created', operator: '+'}],
-            range: [int, int]
-            keys: [string]
     }
     returns {
-            items: [object]
+        items: [object] // list of changelog entries
     }
-
+    see: find
     '''
     response = json_response()
 

pandora/clip/views.py

@@ -74,25 +74,19 @@ def order_query(qs, sort):
 
 def findClips(request, data):
     '''
+    Finds clips for a given query
     takes {
-            query: {
+        query: object, // find clips, query object, see `find`
-                conditions: [object],
+        itemsQuery: object, // limit to matching items, query object, see `find`
-                operator: string // '&' or '|'
+        keys: [string], // list of properties to return
-            },
+        positions: [int], // list of positions
-            itemsQuery: {
+        range: [int, int], // range of results to return
-                conditions: [],
+        sort: [object] // list of sort objects, see `find`
-                operator: string // '&' or '|'
-            },
-            keys: [string],
-            position: int,
-            positions: [string],
-            range: [int, int],
-            sort: []
     }
-
     returns {
-            items: [object]
+        items: [object] // list of clip objects
     }
+    see: find
     '''
     response = json_response()
 

pandora/document/views.py

@@ -65,6 +65,7 @@ actions.register(addDocument, cache=False)
 @login_required_json
 def editDocument(request, data):
     '''
+    Edits data for a document
     takes {
         id: string, // document id
         name: string, // new document name
@@ -141,6 +142,7 @@ def parse_query(data, user):
 
 def findDocuments(request, data):
     '''
+    Finds documents for a given query
     takes {
         query: object, // query object, see `find`
         sort: [object], // list of sort objects, see `find`

pandora/edit/views.py

@@ -206,8 +206,7 @@ def sortClips(request, data):
         edit: string, // edit id
         sort: object // sort
     }
-    returns {
+    returns {}
-    }
     note: sort is [{key: string, operator: string}], operator can be '+' or '-'
     see: addClips, editClip, orderClips, removeClips
     '''
@@ -220,14 +219,16 @@ actions.register(sortClips, cache=False)
 
 def getEdit(request, data):
     '''
+    Gets an edit by id
     takes {
-        id:
+        id: string, // edit id
-        keys: []
+        keys: [string] // list of properties to return
     }
     returns {
-        id:
+        id: string, // edit id
-        clips:
+        clips: [object] // list of clips in this edit
     }
+    see: addEdit, editEdits, findEdits, removeEdit, sortEdits
     '''
     if 'id' in data:
         response = json_response()
@@ -253,7 +254,7 @@ def addEdit(request, data):
         id: string // edit id
         ... // more edit properties
     }
-    see: editEdit, findEdit, removeEdit, sortEdits
+    see: editEdit, findEdit, getEdit, removeEdit, sortEdits
     '''
     data['name'] = re.sub(' \[\d+\]$', '', data.get('name', 'Untitled')).strip()
     name = data['name']
@@ -312,7 +313,7 @@ def editEdit(request, data):
         key: value, // property id and new value
         ... // more key/value pairs
     }
-    see: addEdit, findEdit, removeEdit, sortEdits
+    see: addEdit, findEdit, getEdit, removeEdit, sortEdits
     '''
     edit = get_edit_or_404_json(data['id'])
     response = json_response()
@@ -337,7 +338,7 @@ def removeEdit(request, data):
         id: string // edit id
     }
     returns {}
-    see: addEdit, editEdit findEdit, sortEdits
+    see: addEdit, editEdit, findEdit, getEdit, sortEdits
     '''
     edit = get_edit_or_404_json(data['id'])
     response = json_response()
@@ -388,20 +389,12 @@ def findEdits(request, data):
         range: [int, int], // range of results
         keys: [string] // list of properties to return
     }
-
-    possible query keys:
-        name, user, featured, subscribed
-
-    possible keys:
-        name, user, featured, subscribed, query
-
-    }
     returns {
-        items: [object]
+        items: [object] // list of edit objects
     }
     notes: Possible query keys are 'featured', 'name', 'subscribed' and 'user',
     possible keys are 'featured', 'name', 'query', 'subscribed' and 'user'.
-    see: editEdits, find, removeEdit, sortEdits
+    see: addEdit, editEdits, find, getEdit, removeEdit, sortEdits
     '''
     query = parse_query(data, request.user)
 
@@ -494,7 +487,7 @@ def sortEdits(request, data):
     }
     returns {}
     notes: Sorting featured edits requires a specific per-user capability
-    see: editEdits, findEdits, removeEdit
+    see: addEdit, editEdits, findEdits, getEdit, removeEdit
     '''
     position = 0
     section = data['section']

pandora/entity/views.py

@@ -209,18 +209,12 @@ def findEntities(request, data):
         range: [int, int], // range of results
         keys: [string] // list of properties to return
     }
-
-    possible query keys:
-        name, type
-
-    possible keys:
-        name, type, alternativeNames
-
-    }
     returns {
         items: [object]
     }
-    see: addEntity, editEntity, getEntity, removeEntity
+    notes: Possible query keys are 'name' and 'type', possible keys are
+    'alternativeNames', 'name' and 'type'.
+    see: addEntity, editEntity, find, getEntity, removeEntity
     '''
     query = parse_query(data, request.user)
 

pandora/event/views.py

@@ -184,7 +184,7 @@ def findEvents(request, data):
     returns {
         items: [object] // list of items
     }
-    see: addEvent, editEvent, removeEvent
+    see: addEvent, editEvent, find, removeEvent
     '''
     response = json_response(status=200, text='ok')
     query = parse_query(data, request.user)

pandora/item/views.py

@@ -161,10 +161,10 @@ def find(request, data):
     '$' (ends with), '<', '<=', '>', or '>=', each optionally prefixed with '!'
     (not).
     Leaving out `keys` or passing `positions` can be useful when building a
-    responsive GUI: First leave out `keys` to get totals as fast as possible,
+    responsive UI: First leave out `keys` to get totals as fast as possible,
     then pass `positions` to get the positions of previously selected items,
     finally make the query with `keys` and an appropriate range.
-    For more examples, see the <a href="https://wiki.0x2620.org/wiki/pandora/QuerySyntax">0x2620.org wiki</a>.
+    For more examples, see https://wiki.0x2620.org/wiki/pandora/QuerySyntax.
     see: add, edit, get, lookup, remove, upload
     '''
     if settings.JSON_DEBUG:

pandora/itemlist/views.py

@@ -58,24 +58,19 @@ def parse_query(data, user):
 
 def findLists(request, data):
     '''
+    Finds lists for a given query
     takes {
         query: object, // query object, see `find`
         sort: [], // list of sort objects, see `find`
-        range: [int, int], // range of results
+        range: [int, int], // range of results to return
-        keys: [string] // properties to return
+        keys: [string] // list of properties to return
-    }
-
-    possible query keys:
-        name, user, featured, subscribed
-
-    possible keys:
-        name, user, featured, subscribed, query
-
     }
     returns {
-        items: [{name: string, user: string, featured: bool, public...}]
+        items: [object] // list of list objects
     }
-    see: addList, editList, getList, removeList, sortLists
+    notes: Possible query keys are 'featured', 'name', 'subscribed' and 'user',
+    possible keys are 'featured', 'name', 'query', 'subscribed' and 'user'.
+    see: addList, editList, find, getList, removeList, sortLists
     '''
     query = parse_query(data, request.user)
 

pandora/log/views.py

@@ -17,13 +17,14 @@ import models
 
 def logError(request, data):
     '''
+    Logs an error
     takes {
-            url: string,
+        url: string, // URL
-            line: string,
+        line: string, // line number
-            text: string
+        text: string // error text
-        }
-        returns {
     }
+    returns {}
+    see: findErrorLogs, removeErrorLogs
     '''
     if request.user.is_authenticated():
         user = request.user
@@ -49,10 +50,12 @@ actions.register(logError, cache=False)
 @admin_required_json
 def removeErrorLogs(request, data):
     '''
+    Removes entries from the error log
     takes {
-            ids: [string]
+        ids: [string] // list of error ids
     }
     returns {}
+    see: findErrorLogs, logError
     '''
     models.Log.objects.filter(id__in=[ox.fromAZ(i) for i in data['ids']]).delete()
     response = json_response()
@@ -86,25 +89,17 @@ def order_query(qs, sort):
 @admin_required_json
 def findErrorLogs(request, data):
     '''
+    Finds error logs for a given query
     takes {
-            query: {
+        query: object, // query object, see `find`
-                conditions: [
+        sort: [object], // list of sort objects, see `find`
-                    {
+        range: [int, int], // range of results to return
-                        key: 'user',
+        keys: [string] // list of properties to return
-                        value: 'something',
-                        operator: '='
-                    }
-                ]
-                operator: ","
-            },
-            sort: [{key: 'created', operator: '+'}],
-            range: [int, int]
-            keys: [string]
     }
     returns {
         items: [object]
     }
-
+    see: find, logError, removeErrorLogs
     '''
     response = json_response()
 

pandora/news/views.py

@@ -102,8 +102,8 @@ def editNews(request, data):
         title: string // title
     }
     returns {
-        id: string
+        id: string // news item id
-        ...
+        ... // more properties
     }
     see: addNews, getNews, removeNews
     '''

pandora/person/views.py

@@ -19,15 +19,17 @@ from changelog.models import add_changelog
 @capability_required_json('canManageTitlesAndNames')
 def editName(request, data):
     '''
+    Edits the sort name for a given name
     takes {
-            id: id,
+        id: string, // name id
-            sortname: string
+        sortname: string // sort name
     }
     returns {
-            id: string,
+        id: string, // name id
-            name: string
+        name: string // name
-            ...
+        ... // more properties
     }
+    see: findNames, sortName
     '''
     person = get_object_or_404_json(models.Person, pk=ox.fromAZ(data['id']))
     response = json_response()
@@ -43,14 +45,16 @@ actions.register(editName, cache=False)
 
 def sortName(request, data):
     '''
-        get sort name(s) for given name or names
+    Gets the sort name for one or more names
     takes {
-            names: [string]
+        name: string, // either name
-            name: string
+        names: [string] // or list of names
     }
     returns {
-            name: sortName
+        name: sortName, // sort name for this name
+        ... // more results
     }
+    see editName, findNames
     '''
     names = data.get('names', [])
     if 'name' in data:
@@ -92,56 +96,20 @@ def order_query(qs, sort):
 
 def findNames(request, data):
     '''
+    Finds names for a given query
     takes {
-            query: {
+        query: object, // query object, see `find`
-                conditions: [
+        itemsQuery: object, // limit to matched items, query object, see `find`
-                    {
+        sort: [object], // list of sort objects, see `find`
-                        key: 'user',
+        range: [int, int], // range of results to return
-                        value: 'something',
+        keys: [string] // list of properties to return
-                        operator: '='
     }
-                ]
-                operator: ","
-            },
-            itemsQuery: {
-                //see find request
-            },
-            sort: [{key: 'name', operator: '+'}],
-            range: [0, 100]
-            keys: []
-        }
-
-        possible query keys:
-            name, numberofnames
-
-        possible keys:
-            name, sortname, numberofnames
-        
     returns {
-            items: [{name:, user:, featured:, public...}]
+        items: [object] // list of name objects
-        }
-        param data
-            {'query': query, 'sort': array, 'range': array}
-
-            query: query object, more on query syntax at
-                   https://wiki.0x2620.org/wiki/pandora/QuerySyntax
-            sort: array of key, operator dics
-                [
-                    {
-                        key: "year",
-                        operator: "-"
-                    },
-                    {
-                        key: "director",
-                        operator: ""
-                    }
-                ]
-            range:       result range, array [from, to]
-
-        with keys, items is list of dicts with requested properties:
-        returns {
-              items: [string]
     }
+    notes: Possible query keys are 'name' and 'numberofnames', possible keys
+    are 'name', 'numberofnames' and 'sortname'.
+    see: editName, find, sortName
     '''
     response = json_response()
 

pandora/title/views.py

@@ -20,14 +20,16 @@ import models
 @capability_required_json('canManageTitlesAndNames')
 def editTitle(request, data):
     '''
+    Edits the sort title for a given title
     takes {
-            id: string
+        id: string, // name id
-            sorttitle: string
+        sorttitle: string // sort title
     }
-        can contain any of the allowed keys for title 
     returns {
-            id: string
+        id: string, // title id
+        ... // more properties
     }
+    see: findTitles
     '''
     title = get_object_or_404_json(models.Title, pk=ox.fromAZ(data['id']))
     response = json_response()
@@ -71,59 +73,20 @@ def order_query(qs, sort):
 
 def findTitles(request, data):
     '''
+    Finds titles for a given query
     takes {
-            query: {
+        query: object, // query object, see `find`
-                conditions: [
+        itemsQuery: object, // limit to matched items, query object, see `find`
-                    {
+        sort: [object], // list of sort objects, see `find`
-                        key: 'user',
+        range: [int, int], // range of results to return
-                        value: 'something',
+        keys: [string] // list of properties to return
-                        operator: '='
     }
-                ]
-                operator: ","
-            },
-            itemsQuery: {
-                //see find request
-            },
-            sort: [{key: 'title', operator: '+'}],
-            range: [0, 100]
-            keys: []
-        }
-
-        possible query keys:
-            title, numberoftitles
-
-        possible keys:
-            title, sorttitle, numberoftitles
-        
     returns {
-            items: [object]
+        items: [object] // list of title objects
     }
-
+    notes: Possible query keys are 'numberoftitles' and 'title', possible keys
-        takes {
+    are 'numberoftitles', 'sorttitle' and 'title'.
-            query: object,
+    see: editTitle, find
-            sort: [object],
-            range: [int, int]
-        }
-
-            query: query object, more on query syntax at
-                   https://wiki.0x2620.org/wiki/pandora/QuerySyntax
-            sort: array of key, operator dics
-                [
-                    {
-                        key: "year",
-                        operator: "-"
-                    },
-                    {
-                        key: "director",
-                        operator: ""
-                    }
-                ]
-            range:       result range, array [from, to]
-
-        with keys, items is list of dicts with requested properties:
-          returns {items: [object]}
-
     '''
     response = json_response()