Bump version number and finish all docstrings

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "tennisim"
-version = "0.1.1"
+version = "0.1.2"
 description = "Simple pure python functions for simulating tennis matches"
 authors = ["Mark Jamison <[email protected]>"]
 license = "MIT"

src/tennisim/match.py

@@ -9,6 +9,21 @@
 def prob_match_outcome(
     p_set: float, st_a: int, st_b: int, sets: int = 3
 ) -> Tuple[float, dict]:
+    """Computes probability of player 'a' winning the match given an initial
+    scoreline of (sta_, st_b) and returns a tuple of this prob along with the
+    individual scorelines that make this up e.g. if (0,0) and 0.5 would be:
+    {0.5, {(2,0): 0.5, (2,1): 0.25})
+
+    Args:
+        p_set (float): probability that 'a' wins a given set
+        st_a (int): sets already won by 'a'
+        st_b (int): sets already won by 'b'
+        sets (int, optional): how many sets match is 'best of'. Defaults to 3.
+
+    Returns:
+        Tuple[float, dict]: prob that 'a' wins match and dict of:
+        {score_line: probab}
+    """
 
     # solve corners first - you win by winning best of sets
     win_m = sets // 2 + 1
@@ -47,6 +62,23 @@ def prob_match(
     pt_b: int = 0,
     sets: int = 3,
 ) -> float:
+    """Given a state of a tennis match in sets, games and points; returns the
+    probability that the player will win the match.
+
+    Args:
+        p_a (float): prob that player 'a' wins a point on their serve
+        p_b (float): prob that player 'b' wins a point on their serve
+        st_a (int, optional): sets already won by 'a'. Defaults to 0.
+        st_b (int, optional): sets already won by 'b'. Defaults to 0.
+        g_a (int, optional): games in curr set won by 'a'. Defaults to 0.
+        g_b (int, optional): games in curr set won by 'b'. Defaults to 0.
+        pt_a (int, optional): points in curr game won by 'a'. Defaults to 0.
+        pt_b (int, optional): points in curr game won by 'b'. Defaults to 0.
+        sets (int, optional): how many sets match si 'best of'. Defaults to 3.
+
+    Returns:
+        float: probability that player 'a' wins the match
+    """
 
     # check corners first
     win_m = sets // 2 + 1

src/tennisim/set.py

@@ -14,6 +14,24 @@ def prob_set_outcome(
     f_a: float,
 ) -> float:
 
+    """For a given score outcome in games, returns the probability of that
+    scoreline occurring given:
+     - how many games the current server will serve and return
+     - the prob of them winning service and return games
+
+    Args:
+        score (tuple): games server and returner needs to win for scoreline
+        g_s (int): games current server will serve (ex final game)
+        g_r (int): games current returner will serve (ex final game)
+        s_a (float): prob server wins their service game
+        r_a (float): prob server wins a return game
+        f_a (float): prob server wins final game (already determined if serve
+        or return)
+
+    Returns:
+        float: Probability of set scoreline occuring
+    """
+
     # quick check to ensure that our inputs are correct
     # the sum of games to serve and games to return should equal
     # our desired scoreline
@@ -58,6 +76,20 @@ def prob_set_outcome(
 
 def prob_set(p_a: float, p_b: float, g_a: int, g_b: int) -> float:
 
+    """Given probabilities for server and returner to win points on their
+    respective serves, and the games already won by each, returns the prob
+    that the current server will win the set
+
+    Args:
+        p_a (float): prob current server wins any point on their serve
+        p_b (float): prob current returner wins any point on their serve
+        g_a (int): games already won by current server
+        g_b (int): games already won by current returner
+
+    Returns:
+        float: Probability that current server will win the set
+    """
+
     # solve corners first
     if g_a == 7:
         # then a won either 7-5 or post tiebreak

src/tennisim/tiebreak.py

@@ -104,7 +104,7 @@ def compute_tb_outcomes(
 def create_tb_outcomes(p_a: float, p_b: float, pt_a: int, pt_b: int) -> dict:
     """Given a first to 7 tiebreak, return tiebreak outcomes based on current
     scoreline. This is a helper function required to compute the probability
-    of a given scoreline based on the current score
+    of a given scoreline based on the current score.
 
     Args:
         p_a (float): probability current server wins point on serve
@@ -113,7 +113,7 @@ def create_tb_outcomes(p_a: float, p_b: float, pt_a: int, pt_b: int) -> dict:
         pt_b (int): points current returner has already won
 
     Returns:
-        dict: {final_set_score: data_required_to_compute_prob}
+        dict: {final_tb_score: data_required_to_compute_prob}
     """
 
     # e.g. if current is 3-2 this will create [7-2, 7-3, 7-4, 7-5]
@@ -134,7 +134,13 @@ def prob_tb_outcome(
     p_a: float,
     p_b: float,
 ) -> float:
-    """[summary]
+    """For a given tiebreak score in points, ns, and the respective:
+     - point count that current server will serve and return
+     - prob of winning point on service for each player
+     - prob that current server will win final point
+    returns the probability of that outcome happening by taking into account
+    all the possible paths that make that possible.
+
 
     Args:
         ns (Tuple[int, int]): needed scoreline e.g. (4,0) means current server
@@ -146,7 +152,7 @@ def prob_tb_outcome(
         p_b (float): probability current returner wins point on serve
 
     Returns:
-        float: probability that set ends with given needed scoreline
+        float: probability that tiebreak ends with given scoreline, ns
     """
 
     prob = 0.00