From 65fd71d06ba7dbf664cab39f0a1f77bb1e8afd8a Mon Sep 17 00:00:00 2001
From: Alexander Kryklia <kryklia@gmail.com>
Date: Fri, 4 Jan 2013 15:43:26 +0200
Subject: [PATCH] added documentation for rules

---
 common/lib/capa/capa/graders/draganddrop.py | 36 +++++++++++++++++++++
 docs/source/drag_and_drop_input.rst         |  7 +++-
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/common/lib/capa/capa/graders/draganddrop.py b/common/lib/capa/capa/graders/draganddrop.py
index 4fef58bf7b..431b5d249c 100644
--- a/common/lib/capa/capa/graders/draganddrop.py
+++ b/common/lib/capa/capa/graders/draganddrop.py
@@ -151,6 +151,42 @@ class DragAndDrop(object):
         """ Compares two lists of positions with flag rules. Order of
         correct/user arguments is matter only in 'anyof' flag.
 
+        Rules description:
+
+            'exact' means 1-1 ordered relationship::
+
+                [el1, el2, el3] is 'exact' equal to [el5, el6, el7] when
+                el1 == el5, el2 == el6, el3 == el7.
+                Equality function is custom, see below.
+
+
+            'anyof' means subset relationship::
+
+                user = [el1, el2] is 'anyof' equal to correct = [el1, el2, el3]
+                when
+                        set(user) <= set(correct).
+
+                'anyof' is ordered relationship. It always checks if user
+                is subset of correct
+
+                Equality function is custom, see below.
+
+                Examples:
+
+                     - many draggables per position:
+                    user ['1','2','2','2'] is 'anyof' equal to ['1', '2', '3']
+
+                     - draggables can be placed in any order:
+                    user ['1','2','3','4'] is 'anyof' equal to ['4', '2', '1', 3']
+
+        Equality functions:
+
+        Equality functon depends on type of element. They declared in
+        PositionsCompare class. For position like targets
+        ids ("t1", "t2", etc..) it is string equality function. For coordinate
+        positions ([1,2] or [[1,2], 15]) it is coordinate_positions_compare
+        function (see docstrings in PositionsCompare class)
+
         Args:
             correst, user: lists of positions
 
diff --git a/docs/source/drag_and_drop_input.rst b/docs/source/drag_and_drop_input.rst
index 75e77b97e2..3675de9c96 100644
--- a/docs/source/drag_and_drop_input.rst
+++ b/docs/source/drag_and_drop_input.rst
@@ -29,6 +29,9 @@ be specified for this tag::
     one_per_target - Specify whether to allow more than one draggable to be
           placed onto a single target. It can be either 'true' or 'false'. If
           not specified, the default value is 'true'.
+    no_labels - default is false, in default behaviour if label is not set, label
+          is obtained from id. If no_labels is true, labels are not automatically
+          populated from id, and one can not set labels and obtain only icons.
 
 draggable tag
 -------------
@@ -49,7 +52,8 @@ In order for the grader to work, it is essential that a unique ID
 is provided. Otherwise, there will be no way to tell which draggable is at what
 coordinate, or over what target. Label and icon attributes are optional. If
 they are provided they will be used, otherwise, you can have an empty
-draggable. The path is relative to 'course_folder/static/images/' folder.
+draggable. The path is relative to 'course_folder' folder, for example,
+/static/images/img1.png.
 
 target tag
 ----------
@@ -77,6 +81,7 @@ the slider.
 If no targets are provided, then a draggable can be dragged and placed anywhere
 on the base image.
 
+
 Example
 =======