Add docstrings

epitator/annodoc.py

@@ -1,6 +1,5 @@
 #!/usr/bin/env python
 # coding=utf8
-"""Annotator"""
 from __future__ import absolute_import
 from __future__ import print_function
 from . import maximum_weight_interval_set as mwis

epitator/annospan.py

@@ -54,15 +54,25 @@ def distance(self, other_span):
             return self.start - other_span.end
 
     def overlaps(self, other_span):
+        """
+        Return true if the span overlaps other_span.
+        """
         return (
             (self.start >= other_span.start and self.start < other_span.end) or
             (other_span.start >= self.start and other_span.start < self.end)
         )
 
     def contains(self, other_span):
+        """
+        Return true if the span completely contains other_span.
+        """
         return self.start <= other_span.start and self.end >= other_span.end
 
     def adjacent_to(self, other_span, max_dist=1):
+        """
+        Return true if the span comes before or after other_span with at most
+        max_dist charaters between them.
+        """
         return (
             self.comes_before(other_span, max_dist) or
             other_span.comes_before(self, max_dist)
@@ -114,9 +124,6 @@ def trimmed(self):
             end -= 1
         return AnnoSpan(start, end, self.doc, label=self.label, metadata=self.metadata)
 
-    def size(self):
-        return self.end - self.start
-
     @property
     def text(self):
         return self.doc.text[self.start:self.end]

epitator/annotier.py

@@ -134,8 +134,13 @@ def with_label(self, label):
 
     def optimal_span_set(self, prefer="text_length"):
         """
-        Create a tier with the set of non-overlapping spans from this tier that
-        maximizes the prefer function.
+        :param perfer: A function that takes a span and returns a numeric tuple score.
+            The following predefined functions may be specified via string:
+            text_length, text_length_min_spans, num_spans, and num_spans_and_no_linebreaks
+        :type prefer: string, function
+        :return: A tier with the set of non-overlapping spans from this tier that
+            maximizes the prefer function.
+        :rtype: AnnoTier
 
         >>> from .annospan import AnnoSpan
         >>> from .annodoc import AnnoDoc

epitator/geoname_annotator.py

@@ -535,7 +535,7 @@ def cull_geospans(self, geo_spans):
                 geo_span.start,
                 geo_span.end,
                 # If the size is equal the score is used as a tie breaker.
-                geo_span.size() + geo_span.geoname.score,
+                len(geo_span) + geo_span.geoname.score,
                 geo_span
             )
             for geo_span in geo_spans
@@ -615,6 +615,6 @@ def annotate(self, doc):
                 geo_span = GeoSpan(
                     span.start, span.end, doc, geoname)
                 geo_spans.append(geo_span)
-        culled_geospans = AnnoTier(geo_spans).optimal_span_set(prefer=lambda x: (x.size(), x.geoname.score,))
+        culled_geospans = AnnoTier(geo_spans).optimal_span_set(prefer=lambda x: (len(x), x.geoname.score,))
         logger.info('overlapping geospans removed')
         return {'geonames': culled_geospans}