-

cool-RR · cool-RR · commit e9cf4a516a63 · 2014-09-14T03:16:52.000+03:00
diff --git a/source_py3/python_toolbox/segment_tools.py b/source_py3/python_toolbox/segment_tools.py
@@ -7,6 +7,19 @@
 
 
 def crop_segment(segment, base_segment):
+    '''
+    Crop `segment` to fit inside `base_segment`.
+    
+    This means that if it was partially outside of `base_segment`, that portion
+    would be cut off and you'll get only the intersection of `segment` and
+    `base_segment`.
+    
+    Example:
+    
+        >>> crop_segment((7, 17), (10, 20))
+        (10, 17)
+    
+    '''
     start, end = segment
     base_start, base_end = base_segment
     if not (base_start <= start <= base_end or \
@@ -20,6 +33,20 @@ def crop_segment(segment, base_segment):
 
 
 def merge_segments(segments):
+    '''
+    "Clean" a bunch of segments by removing any shared portions.
+    
+    This function takes an iterable of segments and returns a cleaned one in
+    which any duplicated portions were removed. Some segments which were
+    contained in others would be removed completely, while other segments that
+    touched each other would be merged.
+    
+    Example:
+    
+        >>> merge_segments((0, 10), (4, 16), (16, 17), (30, 40))
+        ((0, 17), (30, 40))
+
+    '''
     assert all(len(segment) == 2 for segment in segments)
     sorted_segments = sorted(segments)
     if not sorted_segments:
