Documentation has been completely revised. Docstrings added

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.

participants/scipy_025/pr_tutorial/simple_functions.py

@@ -1,12 +1,32 @@
 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])
     return values
 
 
 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)
+