Commits

Aleš Erjavec  committed 5e9bb07

Expanded docstrings for context settings.

  • Participants
  • Parent commits 1f06ff1

Comments (0)

Files changed (1)

File _textable/widgets/TextableUtils.py

     """
     Context field for an item list with possible selection indices.
 
-    This field descriptor can be used for storing a list of items for
-    a list view as constructed by :func:`OWGUI.listBox`
+    This field descriptor can be used for storing a list of items
+    (labels) and its selection state for a list view as constructed
+    by :func:`OWGUI.listBox`
 
-    :param str name: Attribute name in the widget.
+    :param str name:
+        Attribute name of the item list in the widget (labels).
     :param str selected:
         Attribute name of a list of indices corresponding to
-        selected items (default: `None` meaning no selection list).
+        selected items (default: `None` meaning there is no selection list).
 
     """
     def __init__(self, name, selected=None):
 
     .. warning::
         When the context is opened (:func:`OWWidget.openContext`) the input
-        list can be changed. For instance the following code can raise
-        an assertion error ::
+        list order can be changed and assigned back to the widget. For
+        instance the following code can raise an assertion error ::
 
             before = self.inputs
             self.openContext("", self.inputs)
         """
         Encode a list of input segmentations.
 
+        Return a list of ```(label, annotations, uuid)``` tuples where
+        `label` is the segmentation label, `annotations` is a sorted tuple
+        of segmentation annotation keys and `uuid` is the unique input
+        widget identifier.
+
         :param list segmentationlist:
-            List of (inputid, Segmentations) tuples.
+            List of (inputid, Segmentation) tuples.
 
         """
         encoded = []
     def match(self, context, imperfect, encodedlist):
         """
         Match the `context` to the encoded segmentations list
+
+        Two contexts match if one encoding is a reordering of the other.
+
         """
         stored = context.encoded
 
         if len(stored) == len(encodedlist):
             if set(stored) == set(encodedlist):
+                # Perfect match
                 return 2
-
+        # No match
         return 0
 
     def _permutation(self, seq1, seq2):
     """
     Context handler for a single :class:`Segmentation` instance.
 
-    Two segmentations are matched if they have the same label and
-    annotation keys.
+    This context handler matches settings on a single instance of
+    :class:`Segmentation`. Two segmentations are matched if they
+    have the same label and annotation keys.
+
+    :param str contextName: Context handler name.
+    :param list fields:
+        A list of :class:`ContextField`. As a convenience if the list
+        contains any strings they are automatically converted to
+        :class:`ContextField` instances.
+    :param bool findImperfect:
+        Unused, should always be the default ``False`` value (this parameter
+        is only present for compatibility with the base class).
 
     """
     def __init__(self, contextName, fields=[], findImperfect=False, **kwargs):
                        for field in fields]
 
     def encode(self, segmentation):
+        """
+        Encode a `Segmentation` instance.
+
+        Return a (label, annotations) tuple where `label` is the
+        segmentation label and `annotations` is a tuple of sorted
+        annotations keys.
+
+        """
         return (segmentation.label,
                 tuple(sorted(segmentation.get_annotation_keys())))
 
 
     def match(self, context, imperfect, encoded):
         """
-        Match the `context` to the encoded segmentation context
+        Match the `context` to the encoded segmentation context.
+
+        Two contexts match if their encodings are structurally
+        equal (==).
+
         """
         return 2 if context.encoded == encoded else 0