Added better docstrings to subpackages and cleaned out some places which were unclear.

evennia/__init__.py

@@ -69,28 +69,34 @@ OOB_HANDLER = None
 CHANNEL_HANDLER = None
 
 
-import os
-from subprocess import check_output, CalledProcessError, STDOUT
-
-__version__ = "Unknown"
-
-root = os.path.dirname(os.path.abspath(__file__))
-try:
-    with open(os.path.join(root, "VERSION.txt"), 'r') as f:
-        __version__ = f.read().strip()
-except IOError as err:
-    print err
-try:
-    __version__ = "%s" % (check_output("git rev-parse --short HEAD", shell=True, cwd=root, stderr=STDOUT).strip())
-except (IOError, CalledProcessError):
-    pass
-
-
-def init():
+def _create_version():
     """
-    This is called by the launcher only after Evennia has fully
-    initialized all its models. It sets up the API in a safe
-    environment where all models are available already.
+    Helper function for building the version string
+    """
+    import os
+    from subprocess import check_output, CalledProcessError, STDOUT
+
+    version = "Unknown"
+    root = os.path.dirname(os.path.abspath(__file__))
+    try:
+        with open(os.path.join(root, "VERSION.txt"), 'r') as f:
+            version = f.read().strip()
+    except IOError as err:
+        print err
+    try:
+        version = "%s (rev %s)" % (version, check_output("git rev-parse --short HEAD", shell=True, cwd=root, stderr=STDOUT).strip())
+    except (IOError, CalledProcessError):
+        pass
+    return version
+
+__version__ = _create_version()
+del _create_version
+
+def _init():
+    """
+    This function is called automatically by the launcher only after
+    Evennia has fully initialized all its models. It sets up the API
+    in a safe environment where all models are available already.
     """
     def imp(path, variable=True):
         "Helper function"

evennia/commands/__init__.py

@@ -1 +1,10 @@
 # -*- coding: utf-8 -*-
+"""
+This sub-package contains Evennia's command system. It handles
+everything related to parsing input from the player, building cmdsets
+and executing the code associated with a found command class.
+
+commands.default contains all the default "mux-like" commands of
+Evennia.
+
+"""

evennia/comms/__init__.py

@@ -1,5 +1,6 @@
 """
-Makes it easier to import by grouping all relevant things already at this
-level.
+This sub-package contains Evennia's comms-system, a set of models and
+handlers for in-game communication via channels and messages as well
+as code related to external communication like IRC or RSS.
 
 """

evennia/comms/channelhandler.py

@@ -82,13 +82,25 @@ class ChannelCommand(command.Command):
 
 class ChannelHandler(object):
     """
-    Handles the set of commands related to channels.
+    The ChannelHandler manages all active in-game channels and
+    dynamically creates channel commands for users so that they can
+    just give the channek's key or alias to write to it. Whenever a
+    new channel is created in the database, the update() method on
+    this handler must be called to sync it with the database (this is
+    done automatically if creating the channel with
+    evennia.create_channel())
+
     """
     def __init__(self):
+        """
+        Initializes the channel handler's internal state.
+
+        """
         self.cached_channel_cmds = []
         self.cached_cmdsets = {}
 
     def __str__(self):
+        "Returns the string representation of the handler"
         return ", ".join(str(cmd) for cmd in self.cached_channel_cmds)
 
     def clear(self):
@@ -133,7 +145,9 @@ class ChannelHandler(object):
         self.cached_cmdsets = {}
 
     def update(self):
-        "Updates the handler completely."
+        """
+        Updates the handler completely.
+        """
         self.cached_channel_cmds = []
         self.cached_cmdsets = {}
         for channel in ChannelDB.objects.get_all_channels():

evennia/contrib/__init__.py

@@ -1 +1,7 @@
 # -*- coding: utf-8 -*-
+"""
+This sub-package holds Evennia's contributions - code that may be
+useful but are deemed too game-specific to go into the core library.
+
+See README.md for more info.
+"""

evennia/game_template/__init__.py

@@ -0,0 +1,6 @@
+"""
+This sub-package holds the template for creating a new game folder.
+The new game folder (when running evennia --init) is a copy of this
+folder.
+
+"""

evennia/help/__init__.py

@@ -1 +1,7 @@
+"""
+This sub-package defines the help system of Evennia. It is pretty
+simple, mainly consisting of a database model to hold help entries.
+The auto-cmd-help is rather handled by the default 'help' command
+itself.
 
+"""

evennia/locks/__init__.py

@@ -1 +1,7 @@
 # -*- coding: utf-8 -*-
+"""
+This sub-package defines the lock (access) mechanism of Evennia. All
+lock strings are processed through the lockhandler in this package. It
+also contains the default lock functions used in lock definitions.
+
+"""

evennia/objects/__init__.py

@@ -1 +1,6 @@
+"""
+This sub-package defines the basic in-game "Object". All in-game
+objects inherit from classes in this package.
+
+"""
 from objects import DefaultObject, DefaultRoom, DefaultExit, DefaultCharacter

evennia/players/__init__.py

@@ -1 +1,7 @@
+"""
+This sub-package defines the out-of-character entities known as
+Players.  These are equivalent to 'accounts' and can puppet one or
+more Objects depending on settings. A Player has no in-game existence.
+
+"""
 from players import DefaultGuest, DefaultPlayer

evennia/scripts/__init__.py

@@ -1 +1,8 @@
+"""
+This sub-package holds the Scripts system. Scripts are database
+entities that can store data both in connection to Objects and Players
+or globally. They may also have a timer-component to execute various
+timed effects.
+
+"""
 from scripts import DefaultScript

evennia/server/__init__.py

@@ -0,0 +1,7 @@
+"""
+This sub-package holds the Server and Portal programs - the "core" of
+Evennia. It also contains the SessionHandler that manages all
+connected users as well as defines all the connection protocols used
+to connect to the game.
+
+"""

evennia/server/evennia_launcher.py

@@ -458,7 +458,7 @@ def check_database():
     if tables and u'players_playerdb' in tables:
         # database exists and seems set up. Initialize evennia.
         import evennia
-        evennia.init()
+        evennia._init()
     # Try to get Player#1
     from evennia.players.models import PlayerDB
     try:

evennia/server/portal/portal.py

@@ -19,7 +19,7 @@ django.setup()
 from django.conf import settings
 
 import evennia
-evennia.init()
+evennia._init()
 
 from evennia.utils.utils import get_evennia_version, mod_import, make_iter
 from evennia.server.portal.portalsessionhandler import PORTAL_SESSIONS

evennia/server/server.py

@@ -18,7 +18,7 @@ import django
 django.setup()
 
 import evennia
-evennia.init()
+evennia._init()
 
 from django.db import connection
 from django.conf import settings

evennia/server/tests.py

@@ -43,5 +43,5 @@ class EvenniaTestSuiteRunner(DiscoverRunner):
         If not given, a subset of settings.INSTALLED_APPS will be used.
         """
         import evennia
-        evennia.init()
+        evennia._init()
         return super(EvenniaTestSuiteRunner, self).build_suite(test_labels, extra_tests=extra_tests, **kwargs)

evennia/settings_default.py

@@ -4,13 +4,13 @@ Master configuration file for Evennia.
 NOTE: NO MODIFICATIONS SHOULD BE MADE TO THIS FILE!
 
 All settings changes should be done by copy-pasting the variable and
-its value to game/settings.py. An empty game/settings.py can be
-auto-generated by running game/manage.py without any arguments.
+its value to <gamedir>/conf/settings.py.
 
 Hint: Don't copy&paste over more from this file than you actually want
 to change.  Anything you don't copy&paste will thus retain its default
 value - which may change as Evennia is developed. This way you can
 always be sure of what you have changed and what is default behaviour.
+
 """
 
 import os

evennia/typeclasses/__init__.py

@@ -1 +1,10 @@
 # -*- coding: utf-8 -*-
+"""
+This sub-package defines the typeclass-system, a way to wrap database
+access into almost-normal Python classes. Using typeclasses one can
+work in normal Python while having the luxury of persistent data
+storage at every turn. ObjectDB, ChannelDB, PlayerDB and ScriptDB all
+inherit from the models in this package. Here is also were the
+Attribute and Tag models are defined along with their handlers.
+
+"""

evennia/utils/__init__.py

@@ -1,3 +1,9 @@
+"""
+This sub-package holds the miscelaneous utilities used by other
+modules in Evennia. It also holds the idmapper in-memory caching
+functionality.
+
+"""
 # simple check to determine if we are currently running under pypy.
 try:
     import __pypy__ as is_pypy

evennia/web/__init__.py

@@ -0,0 +1,7 @@
+"""
+This sub-package holds the web presence of Evennia, using normal
+Django to relate the database contents to web pages. Also the basic
+webclient and the website are defined in here (the webserver itself is
+found under the `server` package).
+"""
+