update api docs

pandora/entity/views.py

@@ -88,14 +88,15 @@ actions.register(addEntity, cache=False)
 
 def autocompleteEntities(request, data):
     '''
+    Returns entities for a given entity type and search string
     takes {
-        key: string,
-        value: string,
+        key: string, // entity type
+        value: string, // search string
         operator: string // '=', '==', '^', '$'
-        range: [int, int]
+        range: [int, int] // range of results to return
     }
     returns {
-        items: [{id, name,...}, ...] // array of matching entities
+        items: [{id, name, ...}, ...] // list of matching entities
     }
     see: autocomplete
     '''

pandora/event/views.py

@@ -130,7 +130,7 @@ def removeEvent(request, data):
     '''
     Removes a calendar event
     takes {
-        id: event id
+        id: string // event id
     }
     returns {}
     see: addEvent, editEvent, findEvents

pandora/item/views.py

@@ -289,15 +289,16 @@ actions.register(find)
 
 def autocomplete(request, data):
     '''
+    Returns autocomplete strings for a given item key and search string
     takes {
-        key: string,
-        value: string,
+        key: string, // item key
+        value: string, // search string
         operator: string, // '=', '==', '^', '$'
         query: object, // item query to limit results, see `find`
-        range: [int, int]
+        range: [int, int] // range of tesults to return
     }
     returns {
-        items: [string, ...] // array of matching values
+        items: [string, ...] // list of matching strings
     }
     see: autocompleteEntities
     '''

pandora/text/views.py

@@ -30,14 +30,16 @@ def get_text_or_404_json(id):
 @login_required_json
 def addText(request, data):
     '''
-        takes {
-            name: value,
-        }
-        returns {
-            id:
-            name:
-            ...
-        }
+    Adds a new text
+    takes {
+        name: string // text name
+    }
+    returns {
+        id: string, // text id
+        name: string // text name
+        ... more key/value pairs
+    }
+    see: editText, findTexts, getText, removeText, sortTexts
     '''
     data['name'] = re.sub(' \[\d+\]$', '', data.get('name', 'Untitled')).strip()
     name = data['name']
@@ -74,15 +76,17 @@ actions.register(addText, cache=False)
 
 def getText(request, data):
     '''
-        takes {
-            id: textid,
-            keys: []
-        }
-        returns {
-            id:
-            text:
-            ...
-        }
+    Gets a text by id
+    takes {
+        id: string, // text id
+        keys: [string] // list of properties to return
+    }
+    returns {
+        id: string, // text id
+        key: value, // property and value
+        ... // more key/value pairs
+    }
+    see: addText, findTexts, editText, removeText, sortTexts
     '''
     response = json_response()
     public_id = data['id']
@@ -113,16 +117,17 @@ actions.register(getText)
 @login_required_json
 def editText(request, data):
     '''
-        takes {
-            id:
-            text:
-            public: boolean
-        }
-        returns {
-            id:
-            text:
-            ...
-        }
+    Edits a text
+    takes {
+        id: string, // text id
+        text: string, // text
+        public: boolean // if true, text is publix
+    }
+    returns {
+        id: string, // text id
+        ... // more key/value pairs
+    }
+    see: addText, findTexts, getText, removeText, sortTexts
     '''
     response = json_response()
     if data['id']:
@@ -185,32 +190,19 @@ def parse_query(data, user):
 
 def findTexts(request, data):
     '''
-        takes {
-            query: {
-                conditions: [
-                    {
-                        key: 'user',
-                        value: 'something',
-                        operator: '='
-                    }
-                ]
-                operator: ","
-            },
-            sort: [{key: 'name', operator: '+'}],
-            range: [0, 100]
-            keys: []
-        }
-
-        possible query keys:
-            name, user, featured, subscribed
-
-        possible keys:
-            name, user, featured, subscribed, query
-
-        }
-        returns {
-            items: [object]
-        }
+    Finds texts for a given query
+    takes {
+        keys: [], // list of keys to return, see `find`
+        query: object, // query object, see `find`
+        range: [int, int], // range of items to return
+        sort: [object], list of sort objects, see `find`
+    }
+    returns {
+        items: [object] // list of text objects
+    }
+    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
     '''
     query = parse_query(data, request.user)
 
@@ -250,11 +242,12 @@ actions.register(findTexts)
 @login_required_json
 def removeText(request, data):
     '''
-        takes {
-            id: string,
-        }
-        returns {
-        }
+    Removes a text
+    takes {
+        id: string // text id
+    }
+    returns {}
+    see: addText, editText, findTexts, getText, sortTexts
     '''
     text = get_text_or_404_json(data['id'])
     response = json_response()
@@ -270,10 +263,13 @@ actions.register(removeText, cache=False)
 @login_required_json
 def subscribeToText(request, data):
     '''
-        takes {
-            id: string,
-        }
-        returns {}
+    Adds a text to favorites
+    takes {
+        id: string, // text id
+        user: string // username (admin-only)
+    }
+    returns {}
+    see: unsubscribeFromText
     '''
     text = get_text_or_404_json(data['id'])
     user = request.user
@@ -294,11 +290,13 @@ actions.register(subscribeToText, cache=False)
 @login_required_json
 def unsubscribeFromText(request, data):
     '''
-        takes {
-            id: string,
-            user: username(only admins)
-        }
-        returns {}
+    Removes a text from favorites
+    takes {
+        id: string // text id
+        user: string // username (admin-only)
+    }
+    returns {}
+    see: subscribeToText
     '''
     text = get_text_or_404_json(data['id'])
     user = request.user
@@ -313,14 +311,14 @@ actions.register(unsubscribeFromText, cache=False)
 @login_required_json
 def sortTexts(request, data):
     '''
-        takes {
-            section: 'personal',
-            ids: [1,2,4,3]
-        }
-            known sections: 'personal', 'public', 'featured'
-            featured can only be edited by admins
-
-        returns {}
+    Sets manual ordering of texts in a given folder
+    takes {
+        section: string, // 'personal', 'favorite' or 'featured'
+        ids: [string] // ordered list of text ids
+    }
+    returns {}
+    notes: Sorting featured texts requires the appropriate capability.
+    see: addText, findTexts, getText, editText, removeText
     '''
     position = 0
     section = data['section']

pandora/user/views.py

@@ -223,18 +223,17 @@ def resetPassword(request, data):
     '''
     Resets password for a given user
     takes {
-        username: string,
-        password: string,
-        code: string
+        username: string, // username
+        password: string, // password
+        code: string // token
     }
     returns {
         errors: {
-            code: 'Incorrect Code'
-        }
-        user {
-        }
+            code: 'Incorrect Code' // on error
+        },
+        user: object // on success
     }
-    see: ...
+    see: resetPassword
     '''
     if 'code' in data and 'password' in data:
         if not data['password']:
@@ -276,16 +275,17 @@ def requestToken(request, data):
     '''
     Requests a password reset token
     takes {
-        username: string,
-        email: string
+        username: string, // either username
+        email: string // or e-mail address
     }
     returns {
         errors: {
-            username: 'Unknown Username'
-            email: 'Unknown Email'
+            username: 'Unknown Username', // on error
+            email: 'Unknown Email' // on error
         }
-        username: user
+        username: string // on success
     }
+    see: requestToken
     '''
     user = None
     if 'username' in data:
@@ -341,12 +341,13 @@ def editUser(request, data):
     '''
     Edits a user
     takes {
-        key: value
-    }
-    required key: id 
-    optional keys: username, email, level, notes
-    returns {
+        id: string, // user id
+        key: value, // property id and new value
+        ... // more key/value pairs
     }
+    returns {}
+    notes: Possible keys are 'email', 'id', 'level', 'notes', 'username'
+    see: removeUser
     '''
     response = json_response()
     user = get_object_or_404_json(User, pk=ox.fromAZ(data['id']))
@@ -395,10 +396,14 @@ actions.register(editUser, cache=False)
 @capability_required_json('canManageUsers')
 def removeUser(request, data):
     '''
+    Removes a user
     takes {
-        username: username
+        username: string // username
     }
     returns {}
+    notes: Note that this will only disable the user account -- annotations
+    will not be removed.
+    see: editUser, findUser
     '''
     response = json_response()
     u = get_user_or_404(data)
@@ -410,17 +415,18 @@ actions.register(removeUser, cache=False)
 
 def findUser(request, data):
     '''
+    Finds users for a given query
     takes {
-        key: string, //username, email
-        value: string,
-        operator: "==" // "==", "="
-        keys: [string]
+        key: string, // username, email
+        value: string, // search string
+        operator: "==" // "==" or "="
+        keys: [string] // list of properties to return
     }
-
     returns {
-        users: [object]
+        users: [object] // list of users
     }
-    see: editUser
+    notes: Possible keys ... undocumented
+    see: editUser, removeUser
     '''
     response = json_response(status=200, text='ok')
     #keys = data.get('keys')