From 9e5fea2d0607cccdd82a3948155fffd522dfc73a Mon Sep 17 00:00:00 2001
From: rolux <rolux@rolux.org>
Date: Sat, 15 Nov 2014 18:39:16 +0000
Subject: [PATCH] start to improve API docs

---
 pandora/annotation/views.py | 46 +++++++++++++++++++++----------------
 pandora/edit/views.py       | 30 ++++++++++++++----------
 pandora/item/views.py       | 18 +++++++--------
 3 files changed, 53 insertions(+), 41 deletions(-)

diff --git a/pandora/annotation/views.py b/pandora/annotation/views.py
index 595088e17..a19499161 100644
--- a/pandora/annotation/views.py
+++ b/pandora/annotation/views.py
@@ -112,17 +112,18 @@ actions.register(findAnnotations)
 @login_required_json
 def addAnnotation(request, data):
     '''
-        takes {
-            item: public_id,
-            layer: layerId,
-            in: float,
-            out: float,
-            value: string
-        }
-        returns {
-            id: string, //id of new annotation
-            ...
-        }
+    Adds a single annotation
+    takes {
+        item: string, (item id)
+        layer: string, (annotation layer id)
+        in: float,
+        out: float,
+        value: string
+    }
+    returns {
+        id: string, (annotation id)
+        ...
+    }
     '''
     for key in ('item', 'layer', 'in', 'out', 'value'):
         if key not in data:
@@ -152,18 +153,23 @@ actions.register(addAnnotation, cache=False)
 @login_required_json
 def addAnnotations(request, data):
     '''
-        takes {
-            item: public_id,
-            layer: layerId,
-            annotations: [{
+    Adds multiple annotations
+    takes {
+        item: string (item id),
+        layer: string (annotation layer id), 
+        annotations: [
+            {
                 in: float,
                 out: float,
                 value: string
-            }, ...]
-        }
-        returns {
-            taskId: string
-        }
+            },
+            ...
+        ]
+    }
+    returns {
+        taskId: string
+    }
+    FIXME: Explain what to do with task id
     '''
     for key in ('item', 'layer', 'annotations'):
         if key not in data:
diff --git a/pandora/edit/views.py b/pandora/edit/views.py
index 00491c5c6..d7e1d36cf 100644
--- a/pandora/edit/views.py
+++ b/pandora/edit/views.py
@@ -27,20 +27,26 @@ def get_edit_or_404_json(id):
 @login_required_json
 def addClips(request, data):
     '''
-        takes {
-            edit: string,
-            index: int,
-            clips: []
-                item: string,
+    Adds one or more clips to an edit
+    takes {
+        edit: string (edit id),
+        index: int (position, optional),
+        clips: [
+            {
+                item: string (item id),
                 in: float,
                 out: float,
-                annotation: string
-        }
-        add clips with item/in/out or annotation to edit with id
-        clips are added at index or end if index is not provided
-        (annoation id is in the form item/annotation)
-        returns {
-        }
+            },
+            {
+                annotation: string ("item_id/annotation_id")
+            }
+            ...
+        ]
+    }
+    returns {}
+    Clips are either {item, in, out} or {annotation}. If index is missing,
+    clips will be inserted at the end of the edit.
+    FIXME: Does this really return nothing?
     '''
     response = json_response()
     edit = get_edit_or_404_json(data['edit'])
diff --git a/pandora/item/views.py b/pandora/item/views.py
index 718705eb7..e6a8173d0 100644
--- a/pandora/item/views.py
+++ b/pandora/item/views.py
@@ -497,16 +497,16 @@ actions.register(get)
 @login_required_json
 def add(request, data):
     '''
-        takes {
-            title: string, //(optional)
-        }
-        returns {
-            id:
-            name:
-            ...
-        }
+    Adds a new item (without video)
+    takes {
+        title: string (optional)
+    }
+    returns {
+        id: string,
+        title: string,
+        ...
+    }
     '''
-
     if not request.user.get_profile().capability('canAddItems'):
         response = json_response(status=403, text='permissino denied')
     else: