better documenation

Author: bloombar

src/examplepackagefb1258/__init__.py

@@ -0,0 +1,10 @@
+"""
+This file is required for Python to recognize the directory as a "regular" package.
+
+Python "regular" packages use the __init__.py file to initialize the package and
+can include package-level variables, import statements, and initialization code
+you wish to run when the package is first imported into a program.
+
+For more information, see the official documentation:
+https://docs.python.org/3/reference/import.html#regular-packages
+"""

src/examplepackagefb1258/__main__.py

@@ -1,10 +1,19 @@
+"""
+In Python packages, this file called __main__.py is run when the package is run
+directly from command line, as opposed to importing it into another program.
+"""
+
 import examplepackagefb1258.wisdom as wisdom
 
 
 def main():
-    line = wisdom.get()
-    print(line)
+    """
+    Get some wise text and print it out.
+    """
+    line = wisdom.get()  # get a line of text
+    print(line)  # print it out
 
 
 if __name__ == "__main__":
+    # run the main function
     main()

src/examplepackagefb1258/wisdom.py

@@ -1,3 +1,8 @@
+"""
+This module provides a function to retrieve a pseudo-random line from Lewis Carroll's poem "The Jabberwocky".
+Read more about Jabberwocky here: https://en.wikipedia.org/wiki/Jabberwocky
+"""
+
 import random