update api docs

pandora/archive/views.py

@@ -161,8 +161,8 @@ def addMedia(request, data):
     '''
     Adds media files to a given item
     takes {
-        filename: string, // undocumented
+        filename: string, // filename
-        id: oshash, // undocumented
+        id: string, // oshash of the file
         info: {}, // undocumented
         item: string // item id
     }

pandora/document/views.py

@@ -72,8 +72,8 @@ def editDocument(request, data):
         item: string // item id (optional)
     }
     returns {
-        id:
+        id: string, // document id
-        ...
+        ... // more document properties
     }
     notes: If `item` is present, this will not edit the global description of
     the document, but its specific description in the context of the given

pandora/edit/views.py

@@ -28,7 +28,7 @@ def get_edit_or_404_json(id):
 @login_required_json
 def addClips(request, data):
     '''
-    Adds one or more clips to an edit
+    Adds one or more clips to a static edit
     takes {
         edit: string, // edit id,
         index: int, // position within edit (optional),
@@ -75,7 +75,7 @@ actions.register(addClips, cache=False)
 @login_required_json
 def removeClips(request, data):
     '''
-    Removes one or more clips from an edit
+    Removes one or more clips from a static edit
     takes {
         edit: string, // edit id
         ids: [string] // clip ids
@@ -109,8 +109,7 @@ def editClip(request, data):
         in: float, // in point in seconds
         out: float // out point in seconds
     }
-    returns {
+    returns {}
-    }
     see: addClips, orderClips, removeClips, sortClips
     '''
     response = json_response()
@@ -245,7 +244,7 @@ actions.register(getEdit)
 @login_required_json
 def addEdit(request, data):
     '''
-    Adds an edit
+    Adds a new edit
     takes {
         name: string, // name (optional)
         type: string // 'static' or 'smart'

pandora/entity/views.py

@@ -33,9 +33,10 @@ def addEntity(request, data):
     '''
     Adds an entity
     takes {
-        type: string,
+        type: string, // entity type, as defined in config
-        name: string,
+        name: string, // name
-        alternativeNames: [string]
+        alternativeNames: [string], // list of alternative names
+        ... // more entity properties, as defined in config
     }
     returns {}
     see: editEntity, findEntities, getEntity, removeEntity
@@ -148,14 +149,14 @@ def editEntity(request, data):
     '''
     Edits an entity
     takes {
-        id: string
+        id: string, // entity id
-        name: string
+        name: string, // entity name
-        description: string
+        description: string, // entity description
-        item(optional): edit descriptoin per item
+        ... // more properties, as defined in config
     }
     returns {
-        id:
+        id: string // entity id
-        ...
+        ... // more entity properties
     }
     see: addEntity, findEntities, getEntity, removeEntity
     '''

pandora/event/views.py

@@ -19,7 +19,7 @@ import models
 @login_required_json
 def addEvent(request, data):
     '''
-    Adds a new calendar event
+    Adds a new event to the calendar
     takes {
         end: string, // 'YYYY-MM-DD HH:MM:SS', arbitrary precision
         name: string, // name
@@ -128,7 +128,7 @@ actions.register(editEvent, cache=False)
 @login_required_json
 def removeEvent(request, data):
     '''
-    Removes a calendar event
+    Removes an event from the calendar
     takes {
         id: string // event id
     }
@@ -175,7 +175,7 @@ def order_query(qs, sort):
 
 def findEvents(request, data):
     '''
-    Finds calendar events
+    Finds calendar events for a given query
     takes {
         query: object, // query object, see `find`
         sort: [object], // list of sort objects, see `find`
@@ -216,12 +216,18 @@ actions.register(findEvents)
 
 def getEventNames(request, data):
     '''
-    Undocumented
+    Gets event names and matches
-    takes {
+    takes {}
-    }
     returns {
-        items: [{name: string, matches: int}]
+        items: [
+            {
+                name: string, // event name
+                matches: int // number of matches in annotations
+            },
+            ... // more events
+        ]
     }
+    see: getPlaceNames
     '''
     response = json_response({})
     layers = [l['id'] for l in filter(lambda l: l['type'] == 'event',

pandora/item/views.py

@@ -164,6 +164,7 @@ def find(request, data):
     responsive GUI: 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>.
     see: add, edit, get, lookup, remove, upload
     '''
     if settings.JSON_DEBUG:
@@ -500,7 +501,7 @@ def add(request, data):
         title: string, // title
         ... // more item properties
     }
-    notes: To allow for this, set config option `itemRequiresVideo` to false
+    notes: To allow for this, set config option `itemRequiresVideo` to false.
     see: edit, find, get, lookup, remove, upload
     '''
     if not request.user.get_profile().capability('canAddItems'):

pandora/itemlist/views.py

@@ -139,7 +139,7 @@ actions.register(getList)
 @login_required_json
 def addListItems(request, data):
     '''
-    Adds one or more items to a list
+    Adds one or more items to a static list
     takes {
         list: string, // list id
         items: [string], // either list of item ids
@@ -169,7 +169,7 @@ actions.register(addListItems, cache=False)
 @login_required_json
 def removeListItems(request, data):
     '''
-    Removes one or more items from a list
+    Removes one or more items from a static list
     takes {
          list: string, // list id
          items: [itemId], // either list of item ids

pandora/place/views.py

@@ -20,24 +20,24 @@ import models
 @login_required_json
 def addPlace(request, data):
     '''
-    Adds a new place
+    Adds a new place to the map
     takes {
-        name: "",
+        name: string, // place name
-        alternativeNames: [],
+        alternativeNames: [string], // list of alternative names
-        geoname: "",
+        geoname: string, // full geoname (like '23 Main St, Foo, Switzerland')
-        countryCode: '',
+        countryCode: string, // two-letter country code (like 'ch')
-        south: float,
+        south: float, // southern edge of the bounding box in degrees
-        west: float,
+        west: float, // western edge of the bounding box in degrees
-        north: float,
+        north: float, // northern edge of the bounding box in degrees
-        east: float,
+        east: float, // eastern edge of the bounding box in degrees
-        lat: float,
+        type: string // place type
-        lng: float,
-        area: float,
-        type: ""
     }
     returns {
         id: string
     }
+    notes: Possible types are 'country', 'region', 'city', 'borough', 'street',
+    'building' and 'feature'.
+    see: editPlace, findPlaces, removePlace
     '''
     #FIXME: check permissions
     exists = False
@@ -105,13 +105,14 @@ def editPlace(request, data):
     '''
     Edits a place
     takes {
-        id: string,
+        id: string, // place id
-        name: string
+        name: string, // place name
-        north: int
+        ... // more place properties
     }
     returns {
-        names: []
+        names: [] // list of names, in case of collision with existing data
     }
+    see: addPlace, findPlaces, removePlace
     '''
     place = get_object_or_404_json(models.Place, pk=ox.fromAZ(data['id']))
     names = data.get('name', [])
@@ -169,9 +170,9 @@ actions.register(editPlace, cache=False)
 @login_required_json
 def removePlace(request, data):
     '''
-    Removes a place
+    Removes a place from the map
     takes {
-        id: string,
+        id: string // place id
     }
     returns {}
     see: addPlace, editPlace, findPlaces
@@ -219,70 +220,20 @@ def order_query(qs, sort):
 
 def findPlaces(request, data):
     '''
+    Finds places for a given query
     takes {
-        query: {
+        query: object, // query object to find places, see `find`
-            conditions: [
+        itemsQuery: object // query object to limit results to items, 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: [int, int]
-        keys: [string]
     }
-
-    possible query keys:
-        name, geoname, user
-
-    itemsQuery can be used to limit the resuts to matches in those items.
-              Uses the same query syntax as used in the find request.
-
-    possible keys:
-        name, geoname, user
-    
     returns {
-        items: [object]
+        items: [object] // list of place objects
     }
-    takes {
+    notes: Possible query keys are 'geoname', 'name' and 'user'. Possible
-        query: object,
+    itemsQuery keys are all item keys, as defined in the config.
-        sort: [object]
+    see: addPlace, editPlace, removePlace
-        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: [string]    
-    }
-
-Positions
-        takes {
-            query: object,
-            positions: [string]
-        }
-        query: query object, more on query syntax at
-               https://wiki.0x2620.org/wiki/pandora/QuerySyntax
-        positions:  ids of places for which positions are required
     '''
     response = json_response()
 
@@ -320,11 +271,18 @@ actions.register(findPlaces)
 
 def getPlaceNames(request, data):
     '''
-    Undocumented
+    Gets place names and matches
     takes {}
     returns {
-        items: [{name: string, matches: int}]
+        items: [
+            {
+                name: string, // place name
+                matches: int // number of matches in annotations
+            },
+            ... // more places
+        ]
     }
+    see: getEventNames
     '''
     response = json_response({})
     layers = [l['id'] for l in filter(lambda l: l['type'] == 'place',

pandora/user/views.py

@@ -669,12 +669,12 @@ def contact(request, data):
     '''
     Sends a message to the contact address
     takes {
-        email: string,
+        email: string, // sender
-        subject: string,
+        subject: string, // subject
-        message: string
+        message: string // message
-    }
-    returns {
     }
+    returns {}
+    see: mail
     '''
     name = data.get('name', '')
     email = data.get('email', '')
@@ -856,7 +856,7 @@ def statistics(request, data):
     Gets usage statistics
     takes {}
     returns {
-        ... // undocumented
+        ... // various statistics
     }
     '''
     response = json_response()
@@ -883,14 +883,20 @@ def group_json(g):
 @login_required_json
 def getGroups(request, data):
     '''
-    Gets user groups
+    Gets all user groups
     takes {}
     returns {
         groups: [
-            {id: string, name: string, users: int, items: int}
+            {
+                id: string, // group id
+                name: string, // group name
+                users: int, // number of users in this group
+                items: int // number of items in this groups
+            },
+            ... // more groups
         ]
     }
-    see: addGroup, editGroup, getGroups, removeGroup
+    see: addGroup, editGroup, getGroup, removeGroup
     '''
     response = json_response(status=200, text='ok')
     response['data']['groups'] = []
@@ -903,17 +909,16 @@ actions.register(getGroups)
 @login_required_json
 def getGroup(request, data):
     '''
-    Gets user group
+    Gets a user group by id or name
     takes {
-        id: string
+        id: string // either group id
-            or
+        name: string // or group name
-        name: string
     }
     returns {
-        id: string,
+        id: string, // group id
-        name: string
+        name: string, // group name
-        users: int
+        users: int, // number of users in this group
-        items: int
+        items: int // number of items in this group
     }
     see: addGroup, editGroup, getGroups, removeGroup
     '''
@@ -927,15 +932,15 @@ actions.register(getGroup, cache=False)
 @capability_required_json('canManageUsers')
 def addGroup(request, data):
     '''
-    Adds user group
+    Adds a new user group
     takes {
-        name: string
+        name: string // group name
     }
     returns {
-        id: string,
+        id: string, // group id
-        name: string
+        name: string, // group name
-        users: int
+        users: int, // number of users in this group
-        items: int
+        items: int // number of items in this group
     }
     see: editGroup, getGroup, getGroups, removeGroup
     '''
@@ -957,15 +962,16 @@ actions.register(addGroup, cache=False)
 @capability_required_json('canManageUsers')
 def editGroup(request, data):
     '''
-    Edits user group
+    Edits a user group
     takes {
-        id: string,
+        id: string, // group id
-        name: string
+        name: string // group name
-        
     }
     returns {
-        name: string
+        id: string, // group id
-        users: int
+        name: string, // group name
+        users: int, // number of users in this group
+        items: int // number of items in this group
     }
     see: addGroup, getGroup, getGroups, removeGroup
     '''
@@ -982,12 +988,11 @@ actions.register(editGroup, cache=False)
 @capability_required_json('canManageUsers')
 def removeGroup(request, data):
     '''
-    Removes user group
+    Removes a user group
     takes {
-        id: string
+        id: string // group id
-    }
-    returns {
     }
+    returns {}
     see: addGroup, editGroup, getGroup, getGroups
     '''
     response = json_response(status=200, text='ok')