Improve docstrings for sphinx.

[python_utils.git] / math_utils.py

diff --git a/math_utils.py b/math_utils.py
index dec34f049aa0382823768c53efc2060ae8c69409..270df8ccb3e8a1fcd5ea3f955438f800fcb69807 100644 (file)
--- a/math_utils.py
+++ b/math_utils.py
@@ -35,7 +35,6 @@ class NumericPopulation(object):
     3
     >>> pop.get_percentile(60)
     7
-
     """
 
     def __init__(self):
@@ -44,7 +43,8 @@ class NumericPopulation(object):
         self.sorted_copy: Optional[List[float]] = None
 
     def add_number(self, number: float):
-        """O(2 log2 n)"""
+        """Adds a number to the population.  Runtime complexity of this
+        operation is :math:`O(2 log_2 n)`"""
 
         if not self.highers or number > self.highers[0]:
             heappush(self.highers, number)
@@ -76,7 +76,8 @@ class NumericPopulation(object):
         return self.aggregate / count
 
     def get_mode(self) -> Tuple[float, int]:
-        """Returns the mode (most common member)."""
+        """Returns the mode (most common member in the population)
+        in O(n) time."""
 
         count: Dict[float, int] = collections.defaultdict(int)
         for n in self.lowers:
@@ -100,10 +101,9 @@ class NumericPopulation(object):
 
     def get_percentile(self, n: float) -> float:
         """Returns the number at approximately pn% (i.e. the nth percentile)
-        of the distribution in O(n log n) time (expensive, requires a
-        complete sort).  Not thread safe.  Caching does across
-        multiple calls without an invocation to add_number.
-
+        of the distribution in O(n log n) time.  Not thread-safe;
+        does caching across multiple calls without an invocation to
+        add_number for perf reasons.
         """
         if n == 50:
             return self.get_median()
@@ -123,6 +123,7 @@ class NumericPopulation(object):
 
 
 def gcd_floats(a: float, b: float) -> float:
+    """Returns the greatest common divisor of a and b."""
     if a < b:
         return gcd_floats(b, a)
 
@@ -133,6 +134,7 @@ def gcd_floats(a: float, b: float) -> float:
 
 
 def gcd_float_sequence(lst: List[float]) -> float:
+    """Returns the greatest common divisor of a list of floats."""
     if len(lst) <= 0:
         raise ValueError("Need at least one number")
     elif len(lst) == 1:
@@ -145,8 +147,7 @@ def gcd_float_sequence(lst: List[float]) -> float:
 
 
 def truncate_float(n: float, decimals: int = 2):
-    """
-    Truncate a float to a particular number of decimals.
+    """Truncate a float to a particular number of decimals.
 
     >>> truncate_float(3.1415927, 3)
     3.141
@@ -167,7 +168,6 @@ def percentage_to_multiplier(percent: float) -> float:
     1.45
     >>> percentage_to_multiplier(-25)
     0.75
-
     """
     multiplier = percent / 100
     multiplier += 1.0
@@ -183,7 +183,6 @@ def multiplier_to_percent(multiplier: float) -> float:
     0.0
     >>> multiplier_to_percent(1.99)
     99.0
-
     """
     percent = multiplier
     if percent > 0.0:
@@ -206,7 +205,6 @@ def is_prime(n: int) -> bool:
     False
     >>> is_prime(51602981)
     True
-
     """
     if not isinstance(n, int):
         raise TypeError("argument passed to is_prime is not of 'int' type")