provide docstrings for all modules, classes, and functions

3 files changed, 28 insertions, 8 deletions

diff --git a/cyberschuessel/__init__.py b/cyberschuessel/__init__.py
index b5cb49c..21e095a 100644
--- a/cyberschuessel/__init__.py
+++ b/cyberschuessel/__init__.py
@@ -1 +1,2 @@
-__version__ = '0.0.1'

+"""Cyberschuessel a implementation of the game Salatschuessel for the cyberspace"""
+__version__ = '0.0.1'
diff --git a/cyberschuessel/schuessel.py b/cyberschuessel/schuessel.py
index 580cb63..354b298 100644
--- a/cyberschuessel/schuessel.py
+++ b/cyberschuessel/schuessel.py
@@ -1,3 +1,4 @@
+"""Implementation of a cyberschuessel"""
 import json
 import logging
 import random
@@ -9,6 +10,7 @@ log = logging.getLogger(__name__)
 
 
 class Schuessel:
+    """Class representing a Saladschuessel and providing a aiohttp handler"""
     def __init__(self):
         self.phase = 0
         self.words = []
@@ -19,11 +21,13 @@ class Schuessel:
         self.clients = {}
 
     def reset(self):
+        """Reset the state of the schuessel"""
         self.phase = 0
         self.words = []
         self.guessed = []
 
     def schuessel_state(self):
+        """Return the client facing state of the schuessel"""
         return {
             'words': len(self.words),
             'guessed': len(self.guessed),
@@ -32,9 +36,17 @@ class Schuessel:
         }
 
     def add(self, word):
+        """Add a word to the schuessel"""
         self.words.append(word)
 
     def draw(self, last_word=None):
+        """Draw a word from the schuessel
+
+        If a last_word is provided which was the last drawn word this
+        word will be counted as guessed and moved to the guessed word list.
+
+        If the word list is empty transfer the guessed list into the words list
+        and start the next phase"""
         phase_change = False
 
         # first draw -> start game
@@ -65,6 +77,7 @@ class Schuessel:
         return word, phase_change
 
     async def broadcast(self, msg):
+        """broadcast any json encodable object to all open websockets"""
         log.info('broadcasting %s to %d', msg, len(self.clients.values()))
         broken_sessions = []
         for session_id, ws in self.clients.items():
@@ -78,10 +91,18 @@ class Schuessel:
             del self.clients[session_id]
 
     async def close_all(self):
+        """close all open websockets"""
         for ws in list(self.clients.values()):
             await ws.close()
 
     async def handler(self, request):
+        """aiohttp handler
+
+        This function delivers the webpage or upgrades the connection to a websocket.
+        Then it listens for events on the socket and executes the
+        commands received from the socket.
+
+        The server logic is implemented in this fnction."""
         ws = aiohttp.web.WebSocketResponse()
         ws_ready = ws.can_prepare(request)
         if not ws_ready.ok:
diff --git a/cyberschuessel/server.py b/cyberschuessel/server.py
index 7b02674..ec425f7 100755
--- a/cyberschuessel/server.py
+++ b/cyberschuessel/server.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+"""aiohttp based webserver running a cyberschuessel app"""
 import argparse
 import logging
 import os
@@ -11,11 +12,8 @@ from aiohttp import web
 from schuessel import Schuessel
 
 
-async def index(request):
-    return aiohttp_jinja2.render_template('index.html', request, {})
-
-
 async def init_app():
+    """Create and initialize a new cyberschuessel aiohttp app"""
     app = web.Application()
     app.on_shutdown.append(shutdown)
 
@@ -37,10 +35,12 @@ async def init_app():
 
 
 async def shutdown(app):
+    """shutdown a cyberschuessel aiohttp app"""
     await app['schuessel'].close_all()
 
 
 def main(args):
+    """init and run a cyberschuessel aiohttp app"""
     logging.basicConfig(level=logging.DEBUG)
 
     app = init_app()
@@ -51,6 +51,4 @@ if __name__ == '__main__':
     parser = argparse.ArgumentParser(description="aiohttp server example")
     parser.add_argument('--port', type=int, default=80)
 
-    args = parser.parse_args()
-
-    main(args)
+    main(parser.parse_args())