Show examples of docstrings.

Python/029_scope.py

@@ -15,7 +15,16 @@ MAX_STUDENTS_PER_TEACHER = 25
 # Let's create a couple functions to get values
 
 # This function makes use of the MAX_TEACHERS global variable
-def get_teacher_count():
+# This is also an example of a "docstring". A docstring is text
+# that is displayed in the IDE and provides additional information
+# to the coder about what the function does and what it returns.
+def get_teacher_count() -> int:
+    """
+    Returns the number of teachers at the school.
+
+    Returns:
+        int: The number of teachers as provided by user input. Value restricted to MAX_TEACHERS.
+    """
     count = 0
     while count == 0:
         # Get a value from the user
@@ -35,7 +44,20 @@ def get_teacher_count():
 
 # This function makes use of the MAX_STUDENTS_PER_TEACHER global variable
 # and is passed the number of teachers obtained from get_teacher_count()
-def get_student_count(teacher_count: int):
+def get_student_count(teacher_count: int) -> int:
+    """
+    Get the number of students at the school from user input.
+    
+    Number will be restricted to:
+    * teacher_count at a minimum,
+    * (teacher_count * MAX_STUDENTS_PER_TEACHER) as a maximum.
+
+    Arguments:
+        teacher_count (int): The number of teachers at the school.
+    
+    Returns:
+        int: The number of students at the school.
+    """
     count = 0
     # Can't have fewer students than teachers
     min_students = teacher_count