From 2737aa5e596b358773b79fd91621897fd3b617e8 Mon Sep 17 00:00:00 2001
From: Filippo Balzaretti <filbalza@stanford.edu>
Date: Sat, 13 Jul 2024 11:53:15 -0700
Subject: [PATCH] Documentation has been completely revised. Docstrings added
 to pr_tutorial/simple_functions.py

---
 participants/scipy_025/doc/README.md          | 58 ++++++++++++++++---
 .../scipy_025/pr_tutorial/simple_functions.py | 20 +++++++
 2 files changed, 69 insertions(+), 9 deletions(-)

diff --git a/participants/scipy_025/doc/README.md b/participants/scipy_025/doc/README.md
index a1542d9..f58b581 100644
--- a/participants/scipy_025/doc/README.md
+++ b/participants/scipy_025/doc/README.md
@@ -1,13 +1,53 @@
-Ok so I guess you are reading this cuz you wanna use my code. There are some
-functions that do stuf and thats:
+# simple_functions.py 
+This script contains two simple functions:
+```python
+fibonacci(max):
+        """ 
+    Generate a list of Fibonacci numbers up to a maximum value.
 
-    >>> from simple_functions import factorial
-    >>> factorial(10)
-    9
+    Args:
+        max (int): The upper limit for the Fibonacci sequence. The function will
+                   generate Fibonacci numbers up to but not exceeding this value.
 
-and this other part does something.  I forget why that I did it:
+    Returns:
+        list: A list containing the Fibonacci sequence up to the specified limit.
+    """
+```
 
-    >>> fibonnaccci(100)
-    [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
+and
 
-If you can't use it, its kind of your problem, not mine!
+```python
+def factorial(value):
+    """ 
+    Calculate the factorial of a given number.
+
+    Args:
+        value (int): The number to calculate the factorial of. Must be a non-negative integer.
+
+    Returns:
+        int: The factorial of the input number. If the input is 0, the function returns 1.
+    """
+```
+
+# buggy_function.py
+The following function
+```python
+def angle_to_sexigesimal(angle_in_degrees, decimals=3):
+    """ 
+    Convert the given angle to a sexigesimal string of hours of RA.
+
+    Parameters
+    ----------
+    angle_in_degrees : float
+        A scalar angle, expressed in degrees
+
+    Returns
+    -------
+    hms_str : str
+        The sexigesimal string giving the hours, minutes, and seconds of RA for
+        the given `angle_in_degrees`
+
+    """
+```
+
+is still buggy and shall therefore not be used.
diff --git a/participants/scipy_025/pr_tutorial/simple_functions.py b/participants/scipy_025/pr_tutorial/simple_functions.py
index c3dcf8f..ca3dc37 100644
--- a/participants/scipy_025/pr_tutorial/simple_functions.py
+++ b/participants/scipy_025/pr_tutorial/simple_functions.py
@@ -1,4 +1,14 @@
 def fibonacci(max):
+    """
+    Generate a list of Fibonacci numbers up to a maximum value.
+
+    Args:
+        max (int): The upper limit for the Fibonacci sequence. The function will
+                   generate Fibonacci numbers up to but not exceeding this value.
+
+    Returns:
+        list: A list containing the Fibonacci sequence up to the specified limit.
+    """
     values = [0, 1]
     while values[-2] + values[-1] < max:
         values.append(values[-2] + values[-1])
@@ -6,7 +16,17 @@ def fibonacci(max):
 
 
 def factorial(value):
+    """
+    Calculate the factorial of a given number.
+
+    Args:
+        value (int): The number to calculate the factorial of. Must be a non-negative integer.
+
+    Returns:
+        int: The factorial of the input number. If the input is 0, the function returns 1.
+    """
     if value == 0:
         return 1
     else:
         return value * factorial(value - 1)
+