From d576c6b638db9f38adcf81aa3f016d5263a42cbc Mon Sep 17 00:00:00 2001
From: rdb <git@rdb.name>
Date: Wed, 24 May 2017 13:29:40 +0200
Subject: [PATCH] Improvements to generated API docs, especially in direct
 tree. Also add an entry point for pfreeze.

---
 direct/src/actor/__init__.py                  |   7 +
 direct/src/controls/__init__.py               |   4 +
 direct/src/directbase/DirectStart.py          |  17 +-
 direct/src/directbase/__init__.py             |  12 ++
 .../src/directdevices/DirectDeviceManager.py  |  83 +++++----
 direct/src/directdevices/DirectRadamec.py     |   2 +-
 direct/src/directdevices/__init__.py          |   5 +
 direct/src/directnotify/__init__.py           |   3 +
 direct/src/directtools/__init__.py            |   8 +
 direct/src/directutil/__init__.py             |   3 +
 .../src/distributed/DistributedSmoothNode.py  |  14 +-
 direct/src/distributed/__init__.py            |   5 +
 direct/src/extensions_native/__init__.py      |   5 +-
 direct/src/filter/__init__.py                 |  11 ++
 direct/src/fsm/ClassicFSM.py                  |  12 +-
 direct/src/fsm/FSM.py                         |   2 +-
 direct/src/fsm/FourState.py                   |   6 +-
 direct/src/fsm/FourStateAI.py                 |   6 +-
 direct/src/fsm/__init__.py                    |   6 +
 direct/src/gui/DirectButton.py                |   2 +-
 direct/src/gui/DirectCheckButton.py           |   4 +-
 direct/src/gui/DirectDialog.py                |   2 +-
 direct/src/gui/DirectEntry.py                 |   3 +-
 direct/src/gui/DirectFrame.py                 |  23 ++-
 direct/src/gui/DirectGuiBase.py               |  49 +++---
 direct/src/gui/DirectGuiGlobals.py            |   8 +-
 direct/src/gui/DirectLabel.py                 |   2 +-
 direct/src/gui/DirectOptionMenu.py            |   2 +-
 direct/src/gui/DirectRadioButton.py           |   5 +-
 direct/src/gui/DirectScrollBar.py             |   2 +-
 direct/src/gui/DirectScrolledFrame.py         |   2 +-
 direct/src/gui/DirectScrolledList.py          |   2 +-
 direct/src/gui/DirectSlider.py                |   2 +-
 direct/src/gui/DirectWaitBar.py               |   2 +-
 direct/src/gui/__init__.py                    |  12 ++
 direct/src/interval/IntervalGlobal.py         |   5 +-
 direct/src/interval/IntervalManager.py        |   6 +-
 direct/src/interval/MetaInterval.py           |   5 +-
 direct/src/interval/ParticleInterval.py       |   6 +-
 direct/src/interval/TestInterval.py           |   8 +-
 direct/src/interval/__init__.py               |  12 ++
 direct/src/motiontrail/__init__.py            |   3 +
 direct/src/p3d/AppRunner.py                   |   7 +-
 direct/src/p3d/__init__.py                    |   4 +
 direct/src/particles/__init__.py              |   7 +
 direct/src/showbase/AppRunnerGlobal.py        |   2 +
 direct/src/showbase/Audio3DManager.py         |   2 +-
 direct/src/showbase/BufferViewer.py           |   4 +-
 direct/src/showbase/BulletinBoard.py          |   2 +-
 direct/src/showbase/BulletinBoardWatcher.py   |   2 +-
 direct/src/showbase/DirectObject.py           |   3 +-
 direct/src/showbase/EventGroup.py             |   2 +-
 direct/src/showbase/EventManager.py           |   3 +-
 direct/src/showbase/EventManagerGlobal.py     |   3 +-
 direct/src/showbase/Factory.py                |   2 +-
 direct/src/showbase/FindCtaPaths.py           |   6 +-
 direct/src/showbase/Finder.py                 |   2 +-
 direct/src/showbase/GarbageReport.py          |   2 +-
 direct/src/showbase/Messenger.py              |   3 +-
 direct/src/showbase/MirrorDemo.py             |   6 +-
 direct/src/showbase/ObjectPool.py             |   2 +-
 direct/src/showbase/ObjectReport.py           |  22 ++-
 direct/src/showbase/OnScreenDebug.py          |   2 +-
 direct/src/showbase/Pool.py                   |  17 +-
 direct/src/showbase/SfxPlayer.py              |   6 +-
 direct/src/showbase/ShadowDemo.py             |   7 +-
 direct/src/showbase/ShadowPlacer.py           |   6 +-
 direct/src/showbase/TaskThreaded.py           |   5 +-
 direct/src/showbase/ThreeUpShow.py            |   3 +-
 direct/src/showbase/Transitions.py            |   4 +-
 direct/src/showbase/VerboseImport.py          |   5 +-
 direct/src/showutil/pfreeze.py                | 165 +++++++++---------
 direct/src/stdpy/__init__.py                  |   5 +
 direct/src/task/TaskManagerGlobal.py          |   1 +
 direct/src/task/TaskTester.py                 |   7 +-
 direct/src/task/Timer.py                      |   2 +-
 direct/src/task/__init__.py                   |   8 +
 direct/src/tkpanels/NotifyPanel.py            |   2 +-
 direct/src/tkwidgets/SceneGraphExplorer.py    |   5 +-
 direct/src/tkwidgets/Tree.py                  |   2 +-
 .../src/tkwidgets/WidgetPropertiesDialog.py   |   2 +-
 dtool/src/dtoolbase/typedObject.h             |   2 +
 dtool/src/interrogate/interrogateBuilder.cxx  |   4 +
 makepanda/makewheel.py                        |   1 +
 panda/src/pgraph/lightRampAttrib.cxx          |  43 +++--
 panda/src/physics/linearUserDefinedForce.h    |   7 +-
 86 files changed, 490 insertions(+), 285 deletions(-)

diff --git a/direct/src/actor/__init__.py b/direct/src/actor/__init__.py
index e69de29bb2..8a080475bb 100644
--- a/direct/src/actor/__init__.py
+++ b/direct/src/actor/__init__.py
@@ -0,0 +1,7 @@
+"""
+This package contains the :class:`.Actor` class as well as a
+distributed variant thereof.  Actor is a high-level interface around
+the lower-level :class:`panda3d.core.Character` implementation.
+It loads and controls an animated character and manages the animations
+playing on it.
+"""
diff --git a/direct/src/controls/__init__.py b/direct/src/controls/__init__.py
index e69de29bb2..811657484c 100644
--- a/direct/src/controls/__init__.py
+++ b/direct/src/controls/__init__.py
@@ -0,0 +1,4 @@
+"""
+This package contains various types of character controllers, handling basic
+control mechanics and setting up collisions for them.
+"""
diff --git a/direct/src/directbase/DirectStart.py b/direct/src/directbase/DirectStart.py
index 031dc85323..8b6b5b9539 100644
--- a/direct/src/directbase/DirectStart.py
+++ b/direct/src/directbase/DirectStart.py
@@ -1,4 +1,19 @@
-""" This is a deprecated module that creates a global instance of ShowBase. """
+"""
+This is a shortcut that instantiates ShowBase automatically on import,
+opening a graphical window and setting up the scene graph.
+This example demonstrates its use:
+
+   import direct.directbase.DirectStart
+   run()
+
+While it may be considered useful for quick prototyping in the interactive
+Python shell, using it in applications is not considered good style.
+As such, it has been deprecated starting with Panda3D 1.9.  It is equivalent
+to and may be replaced by the following code:
+
+   from direct.showbase.ShowBase import ShowBase
+   base = ShowBase()
+"""
 
 __all__ = []
 
diff --git a/direct/src/directbase/__init__.py b/direct/src/directbase/__init__.py
index e69de29bb2..0d7c008a72 100644
--- a/direct/src/directbase/__init__.py
+++ b/direct/src/directbase/__init__.py
@@ -0,0 +1,12 @@
+"""
+This package contains modules to quickly set up a Panda environment for
+quick prototyping in the interactive Python shell.  Merely importing
+one of these modules will create a :class:`.ShowBase` instance, opening
+a graphical window and setting up the scene graph.
+
+The most commonly used module from this package is :mod:`.DirectStart`,
+importing which executes the following code::
+
+   from direct.showbase.ShowBase import ShowBase
+   base = ShowBase()
+"""
diff --git a/direct/src/directdevices/DirectDeviceManager.py b/direct/src/directdevices/DirectDeviceManager.py
index 78c8615bdf..76206f6c40 100644
--- a/direct/src/directdevices/DirectDeviceManager.py
+++ b/direct/src/directdevices/DirectDeviceManager.py
@@ -9,10 +9,6 @@ ANALOG_MAX = 0.95
 ANALOG_DEADBAND = 0.125
 ANALOG_CENTER = 0.0
 
-try:
-    myBase = base
-except:
-    myBase = simbase
 
 class DirectDeviceManager(VrpnClient, DirectObject):
     def __init__(self, server = None):
@@ -52,8 +48,13 @@ class DirectButtons(ButtonNode, DirectObject):
         ButtonNode.__init__(self, vrpnClient, device)
         # Create a unique name for this button object
         self.name = 'DirectButtons-' + repr(DirectButtons.buttonCount)
+
         # Attach node to data graph
-        self.nodePath = myBase.dataRoot.attachNewNode(self)
+        try:
+            self._base = base
+        except:
+            self._base = simbase
+        self.nodePath = self._base.dataRoot.attachNewNode(self)
 
     def __getitem__(self, index):
         if (index < 0) or (index >= self.getNumButtons()):
@@ -64,10 +65,10 @@ class DirectButtons(ButtonNode, DirectObject):
         return self.getNumButtons()
 
     def enable(self):
-        self.nodePath.reparentTo(myBase.dataRoot)
+        self.nodePath.reparentTo(self._base.dataRoot)
 
     def disable(self):
-        self.nodePath.reparentTo(myBase.dataUnused)
+        self.nodePath.reparentTo(self._base.dataUnused)
 
     def getName(self):
         return self.name
@@ -83,6 +84,12 @@ class DirectButtons(ButtonNode, DirectObject):
 
 class DirectAnalogs(AnalogNode, DirectObject):
     analogCount = 0
+
+    _analogDeadband = ConfigVariableDouble('vrpn-analog-deadband', ANALOG_DEADBAND)
+    _analogMin = ConfigVariableDouble('vrpn-analog-min', ANALOG_MIN)
+    _analogMax = ConfigVariableDouble('vrpn-analog-max', ANALOG_MAX)
+    _analogCenter = ConfigVariableDouble('vrpn-analog-center', ANALOG_CENTER)
+
     def __init__(self, vrpnClient, device):
         # Keep track of number of analogs created
         DirectAnalogs.analogCount += 1
@@ -90,19 +97,20 @@ class DirectAnalogs(AnalogNode, DirectObject):
         AnalogNode.__init__(self, vrpnClient, device)
         # Create a unique name for this analog object
         self.name = 'DirectAnalogs-' + repr(DirectAnalogs.analogCount)
-        # Attach node to data graph
-        self.nodePath = myBase.dataRoot.attachNewNode(self)
-        # See if any of the general analog parameters are dconfig'd
-        self.analogDeadband = myBase.config.GetFloat('vrpn-analog-deadband',
-                                                     ANALOG_DEADBAND)
-        self.analogMin = myBase.config.GetFloat('vrpn-analog-min',
-                                                ANALOG_MIN)
-        self.analogMax = myBase.config.GetFloat('vrpn-analog-max',
-                                                ANALOG_MAX)
-        self.analogCenter = myBase.config.GetFloat('vrpn-analog-center',
-                                                   ANALOG_CENTER)
-        self.analogRange = self.analogMax - self.analogMin
 
+        # Attach node to data graph
+        try:
+            self._base = base
+        except:
+            self._base = simbase
+        self.nodePath = self._base.dataRoot.attachNewNode(self)
+
+        # See if any of the general analog parameters are dconfig'd
+        self.analogDeadband = self._analogDeadband.getValue()
+        self.analogMin = self._analogMin.getValue()
+        self.analogMax = self._analogMax.getValue()
+        self.analogCenter = self._analogCenter.getValue()
+        self.analogRange = self.analogMax - self.analogMin
 
     def __getitem__(self, index):
         if (index < 0) or (index >= self.getNumControls()):
@@ -113,10 +121,10 @@ class DirectAnalogs(AnalogNode, DirectObject):
         return self.getNumControls()
 
     def enable(self):
-        self.nodePath.reparentTo(myBase.dataRoot)
+        self.nodePath.reparentTo(self._base.dataRoot)
 
     def disable(self):
-        self.nodePath.reparentTo(myBase.dataUnused)
+        self.nodePath.reparentTo(self._base.dataUnused)
 
     def normalizeWithoutCentering(self, val, minVal = -1, maxVal = 1):
         #
@@ -186,14 +194,19 @@ class DirectTracker(TrackerNode, DirectObject):
         TrackerNode.__init__(self, vrpnClient, device)
         # Create a unique name for this tracker object
         self.name = 'DirectTracker-' + repr(DirectTracker.trackerCount)
+
         # Attach node to data graph
-        self.nodePath = myBase.dataRoot.attachNewNode(self)
+        try:
+            self._base = base
+        except:
+            self._base = simbase
+        self.nodePath = self._base.dataRoot.attachNewNode(self)
 
     def enable(self):
-        self.nodePath.reparentTo(myBase.dataRoot)
+        self.nodePath.reparentTo(self._base.dataRoot)
 
     def disable(self):
-        self.nodePath.reparentTo(myBase.dataUnused)
+        self.nodePath.reparentTo(self._base.dataUnused)
 
     def getName(self):
         return self.name
@@ -213,8 +226,13 @@ class DirectDials(DialNode, DirectObject):
         DialNode.__init__(self, vrpnClient, device)
         # Create a unique name for this dial object
         self.name = 'DirectDials-' + repr(DirectDials.dialCount)
+
         # Attach node to data graph
-        self.nodePath = myBase.dataRoot.attachNewNode(self)
+        try:
+            self._base = base
+        except:
+            self._base = simbase
+        self.nodePath = self._base.dataRoot.attachNewNode(self)
 
     def __getitem__(self, index):
         """
@@ -227,10 +245,10 @@ class DirectDials(DialNode, DirectObject):
         return self.getNumDials()
 
     def enable(self):
-        self.nodePath.reparentTo(myBase.dataRoot)
+        self.nodePath.reparentTo(self._base.dataRoot)
 
     def disable(self):
-        self.nodePath.reparentTo(myBase.dataUnused)
+        self.nodePath.reparentTo(self._base.dataUnused)
 
     def getName(self):
         return self.name
@@ -259,14 +277,19 @@ class DirectTimecodeReader(AnalogNode, DirectObject):
         self.seconds = 0
         self.minutes = 0
         self.hours = 0
+
         # Attach node to data graph
-        self.nodePath = myBase.dataRoot.attachNewNode(self)
+        try:
+            self._base = base
+        except:
+            self._base = simbase
+        self.nodePath = self._base.dataRoot.attachNewNode(self)
 
     def enable(self):
-        self.nodePath.reparentTo(myBase.dataRoot)
+        self.nodePath.reparentTo(self._base.dataRoot)
 
     def disable(self):
-        self.nodePath.reparentTo(myBase.dataUnused)
+        self.nodePath.reparentTo(self._base.dataUnused)
 
     def getName(self):
         return self.name
diff --git a/direct/src/directdevices/DirectRadamec.py b/direct/src/directdevices/DirectRadamec.py
index 2aa7b1933c..3f74162b9b 100644
--- a/direct/src/directdevices/DirectRadamec.py
+++ b/direct/src/directdevices/DirectRadamec.py
@@ -21,7 +21,7 @@ class DirectRadamec(DirectObject):
     radamecCount = 0
     notify = DirectNotifyGlobal.directNotify.newCategory('DirectRadamec')
 
-    def __init__(self, device = 'Analog0', nodePath = base.direct.camera):
+    def __init__(self, device = 'Analog0', nodePath = None):
         # See if device manager has been initialized
         if base.direct.deviceManager == None:
             base.direct.deviceManager = DirectDeviceManager()
diff --git a/direct/src/directdevices/__init__.py b/direct/src/directdevices/__init__.py
index e69de29bb2..46728797fa 100644
--- a/direct/src/directdevices/__init__.py
+++ b/direct/src/directdevices/__init__.py
@@ -0,0 +1,5 @@
+"""
+This package contains a high-level interface for VRPN devices.
+
+Also see the :mod:`panda3d.vprn` module.
+"""
diff --git a/direct/src/directnotify/__init__.py b/direct/src/directnotify/__init__.py
index e69de29bb2..96706bb8ad 100644
--- a/direct/src/directnotify/__init__.py
+++ b/direct/src/directnotify/__init__.py
@@ -0,0 +1,3 @@
+"""
+This package contains notification and logging utilities for Python code.
+"""
diff --git a/direct/src/directtools/__init__.py b/direct/src/directtools/__init__.py
index e69de29bb2..14c68c31bf 100644
--- a/direct/src/directtools/__init__.py
+++ b/direct/src/directtools/__init__.py
@@ -0,0 +1,8 @@
+"""
+This package contains the DIRECT tools, a set of tkinter tools for exploring
+and manipulating the Panda3D scene graph.  By default, these are disabled,
+but they can be explicitly enabled using the following PRC configuration::
+
+   want-directtools true
+   want-tk true
+"""
diff --git a/direct/src/directutil/__init__.py b/direct/src/directutil/__init__.py
index e69de29bb2..b242b7639e 100644
--- a/direct/src/directutil/__init__.py
+++ b/direct/src/directutil/__init__.py
@@ -0,0 +1,3 @@
+"""
+This package contains assorted utility classes.
+"""
diff --git a/direct/src/distributed/DistributedSmoothNode.py b/direct/src/distributed/DistributedSmoothNode.py
index 1d6aef43fb..9bc75c1da1 100644
--- a/direct/src/distributed/DistributedSmoothNode.py
+++ b/direct/src/distributed/DistributedSmoothNode.py
@@ -7,19 +7,21 @@ from . import DistributedNode
 from . import DistributedSmoothNodeBase
 from direct.task.Task import cont
 
+config = get_config_showbase()
+
 # This number defines our tolerance for out-of-sync telemetry packets.
 # If a packet appears to have originated from more than MaxFuture
 # seconds in the future, assume we're out of sync with the other
 # avatar and suggest a resync for both.
-MaxFuture = base.config.GetFloat("smooth-max-future", 0.2)
+MaxFuture = config.GetFloat("smooth-max-future", 0.2)
 
 # How frequently can we suggest a resynchronize with another client?
-MinSuggestResync = base.config.GetFloat("smooth-min-suggest-resync", 15)
+MinSuggestResync = config.GetFloat("smooth-min-suggest-resync", 15)
 
 # These flags indicate whether global smoothing and/or prediction is
 # allowed or disallowed.
-EnableSmoothing = base.config.GetBool("smooth-enable-smoothing", 1)
-EnablePrediction = base.config.GetBool("smooth-enable-prediction", 1)
+EnableSmoothing = config.GetBool("smooth-enable-smoothing", 1)
+EnablePrediction = config.GetBool("smooth-enable-prediction", 1)
 
 # These values represent the amount of time, in seconds, to delay the
 # apparent position of other avatars, when non-predictive and
@@ -27,8 +29,8 @@ EnablePrediction = base.config.GetBool("smooth-enable-prediction", 1)
 # addition to the automatic delay of the observed average latency from
 # each avatar, which is intended to compensate for relative clock
 # skew.
-Lag = base.config.GetDouble("smooth-lag", 0.2)
-PredictionLag = base.config.GetDouble("smooth-prediction-lag", 0.0)
+Lag = config.GetDouble("smooth-lag", 0.2)
+PredictionLag = config.GetDouble("smooth-prediction-lag", 0.0)
 
 
 GlobalSmoothing = 0
diff --git a/direct/src/distributed/__init__.py b/direct/src/distributed/__init__.py
index e69de29bb2..cf5b4bc502 100644
--- a/direct/src/distributed/__init__.py
+++ b/direct/src/distributed/__init__.py
@@ -0,0 +1,5 @@
+"""
+This package contains an implementation of the Distributed Networking
+API, a high-level networking system that automatically propagates
+changes made on distributed objects to interested clients.
+"""
diff --git a/direct/src/extensions_native/__init__.py b/direct/src/extensions_native/__init__.py
index 8b13789179..093c05df15 100644
--- a/direct/src/extensions_native/__init__.py
+++ b/direct/src/extensions_native/__init__.py
@@ -1 +1,4 @@
-
+"""
+This package contains various Python methods that extend some of Panda's
+underlying C++ classes.
+"""
diff --git a/direct/src/filter/__init__.py b/direct/src/filter/__init__.py
index e69de29bb2..4acb30b438 100644
--- a/direct/src/filter/__init__.py
+++ b/direct/src/filter/__init__.py
@@ -0,0 +1,11 @@
+"""
+This package contains functionality for applying post-processing
+filters to the result of rendering a 3-D scene.  This is done by
+rendering the scene to an off-screen buffer, and then applying this to
+a full-screen card that has a shader applied which manipulates the
+texture values as desired.
+
+The :class:`.CommonFilters` class contains various filters that are
+provided out of the box, whereas the :class:`.FilterManager` class
+is a lower-level class that allows you to set up your own filters.
+"""
diff --git a/direct/src/fsm/ClassicFSM.py b/direct/src/fsm/ClassicFSM.py
index 847cf290db..c954718e4d 100644
--- a/direct/src/fsm/ClassicFSM.py
+++ b/direct/src/fsm/ClassicFSM.py
@@ -1,13 +1,13 @@
-"""Undocumented Module"""
-
-__all__ = ['ClassicFSM']
-
 """Finite State Machine module: contains the ClassicFSM class.
 
-This module and class exist only for backward compatibility with
-existing code.  New code should use the FSM module instead.
+.. note::
+
+   This module and class exist only for backward compatibility with
+   existing code.  New code should use the :mod:`.FSM` module instead.
 """
 
+__all__ = ['ClassicFSM']
+
 from direct.directnotify.DirectNotifyGlobal import directNotify
 from direct.showbase.DirectObject import DirectObject
 import weakref
diff --git a/direct/src/fsm/FSM.py b/direct/src/fsm/FSM.py
index 3aa583f007..6af064e3d7 100644
--- a/direct/src/fsm/FSM.py
+++ b/direct/src/fsm/FSM.py
@@ -1,5 +1,5 @@
 """The new Finite State Machine module. This replaces the module
-previously called FSM.py (now called ClassicFSM.py).
+previously called FSM (now called :mod:`.ClassicFSM`).
 """
 
 __all__ = ['FSMException', 'FSM']
diff --git a/direct/src/fsm/FourState.py b/direct/src/fsm/FourState.py
index af7b7d650c..5188284baf 100755
--- a/direct/src/fsm/FourState.py
+++ b/direct/src/fsm/FourState.py
@@ -1,9 +1,7 @@
-"""Undocumented Module"""
+"""Contains the FourState class."""
 
 __all__ = ['FourState']
 
-
-
 from direct.directnotify import DirectNotifyGlobal
 #import DistributedObject
 from . import ClassicFSM
@@ -20,7 +18,7 @@ class FourState:
     Inherit from FourStateFSM and pass in your states.  Two of
     the states should be oposites of each other and the other
     two should be the transition states between the first two.
-    E.g.
+    E.g::
 
                     +--------+
                  -->| closed | --
diff --git a/direct/src/fsm/FourStateAI.py b/direct/src/fsm/FourStateAI.py
index eee4b43a76..a17b9e4c62 100755
--- a/direct/src/fsm/FourStateAI.py
+++ b/direct/src/fsm/FourStateAI.py
@@ -1,9 +1,7 @@
-"""Undocumented Module"""
+"""Contains the FourStateAI class.  See also :mod:`.FourState`."""
 
 __all__ = ['FourStateAI']
 
-
-
 from direct.directnotify import DirectNotifyGlobal
 #import DistributedObjectAI
 from . import ClassicFSM
@@ -21,7 +19,7 @@ class FourStateAI:
     Inherit from FourStateFSM and pass in your states.  Two of
     the states should be oposites of each other and the other
     two should be the transition states between the first two.
-    E.g.
+    E.g::
 
                     +--------+
                  -->| closed | --
diff --git a/direct/src/fsm/__init__.py b/direct/src/fsm/__init__.py
index e69de29bb2..365e539c4e 100644
--- a/direct/src/fsm/__init__.py
+++ b/direct/src/fsm/__init__.py
@@ -0,0 +1,6 @@
+"""
+This package contains implementations of a Finite State Machine, an
+abstract construct that holds a particular state and can transition
+between several defined states.  These are useful for a range of logic
+programming tasks.
+"""
diff --git a/direct/src/gui/DirectButton.py b/direct/src/gui/DirectButton.py
index 87077d20a0..e6111af710 100644
--- a/direct/src/gui/DirectButton.py
+++ b/direct/src/gui/DirectButton.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""This module contains the DirectButton class."""
 
 __all__ = ['DirectButton']
 
diff --git a/direct/src/gui/DirectCheckButton.py b/direct/src/gui/DirectCheckButton.py
index 3df28a0730..f353f3d989 100644
--- a/direct/src/gui/DirectCheckButton.py
+++ b/direct/src/gui/DirectCheckButton.py
@@ -1,4 +1,6 @@
-"""Undocumented Module"""
+"""A DirectCheckButton is a type of button that toggles between two states
+when clicked.  It also has a separate indicator that can be modified
+separately."""
 
 __all__ = ['DirectCheckButton']
 
diff --git a/direct/src/gui/DirectDialog.py b/direct/src/gui/DirectDialog.py
index 039092c511..33852dc504 100644
--- a/direct/src/gui/DirectDialog.py
+++ b/direct/src/gui/DirectDialog.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""This module defines various dialog windows for the DirectGUI system."""
 
 __all__ = ['findDialog', 'cleanupDialog', 'DirectDialog', 'OkDialog', 'OkCancelDialog', 'YesNoDialog', 'YesNoCancelDialog', 'RetryCancelDialog']
 
diff --git a/direct/src/gui/DirectEntry.py b/direct/src/gui/DirectEntry.py
index 45733b7c35..2eb7607400 100644
--- a/direct/src/gui/DirectEntry.py
+++ b/direct/src/gui/DirectEntry.py
@@ -1,4 +1,5 @@
-"""Undocumented Module"""
+"""Contains the DirectEntry class, a type of DirectGUI widget that accepts
+text entered using the keyboard."""
 
 __all__ = ['DirectEntry']
 
diff --git a/direct/src/gui/DirectFrame.py b/direct/src/gui/DirectFrame.py
index 9c164038b9..e078b28021 100644
--- a/direct/src/gui/DirectFrame.py
+++ b/direct/src/gui/DirectFrame.py
@@ -1,4 +1,17 @@
-"""Undocumented Module"""
+"""A DirectFrame is a basic DirectGUI component that acts as the base
+class for various other components, and can also serve as a basic
+container to hold other DirectGUI components.
+
+A DirectFrame can have:
+
+* A background texture (pass in path to image, or Texture Card)
+* A midground geometry item (pass in geometry)
+* A foreground text Node (pass in text string or OnscreenText)
+
+Each of these has 1 or more states.  The same object can be used for
+all states or each state can have a different text/geom/image (for
+radio button and check button indicators, for example).
+"""
 
 __all__ = ['DirectFrame']
 
@@ -19,14 +32,6 @@ class DirectFrame(DirectGuiWidget):
     DefDynGroups = ('text', 'geom', 'image')
     def __init__(self, parent = None, **kw):
         # Inherits from DirectGuiWidget
-        # A Direct Frame can have:
-        # - A background texture (pass in path to image, or Texture Card)
-        # - A midground geometry item (pass in geometry)
-        # - A foreground text Node (pass in text string or Onscreen Text)
-        # Each of these has 1 or more states
-        # The same object can be used for all states or each
-        # state can have a different text/geom/image (for radio button
-        # and check button indicators, for example).
         optiondefs = (
             # Define type of DirectGuiWidget
             ('pgFunc',          PGItem,     None),
diff --git a/direct/src/gui/DirectGuiBase.py b/direct/src/gui/DirectGuiBase.py
index 833bf8ebcb..6836f7465f 100644
--- a/direct/src/gui/DirectGuiBase.py
+++ b/direct/src/gui/DirectGuiBase.py
@@ -1,32 +1,7 @@
-"""Undocumented Module"""
-
-__all__ = ['DirectGuiBase', 'DirectGuiWidget']
-
-
-from panda3d.core import *
-from panda3d.direct import get_config_showbase
-from . import DirectGuiGlobals as DGG
-from .OnscreenText import *
-from .OnscreenGeom import *
-from .OnscreenImage import *
-from direct.directtools.DirectUtil import ROUND_TO
-from direct.showbase import DirectObject
-from direct.task import Task
-import sys
-
-if sys.version_info >= (3, 0):
-    stringType = str
-else:
-    stringType = basestring
-
-guiObjectCollector = PStatCollector("Client::GuiObjects")
-
 """
 Base class for all Direct Gui items.  Handles composite widgets and
 command line argument parsing.
-"""
 
-"""
 Code Overview:
 
 1   Each widget defines a set of options (optiondefs) as a list of tuples
@@ -101,7 +76,31 @@ Code Overview:
     are left unused.  If so, an error is raised.
 """
 
+__all__ = ['DirectGuiBase', 'DirectGuiWidget']
+
+
+from panda3d.core import *
+from panda3d.direct import get_config_showbase
+from . import DirectGuiGlobals as DGG
+from .OnscreenText import *
+from .OnscreenGeom import *
+from .OnscreenImage import *
+from direct.directtools.DirectUtil import ROUND_TO
+from direct.showbase import DirectObject
+from direct.task import Task
+import sys
+
+if sys.version_info >= (3, 0):
+    stringType = str
+else:
+    stringType = basestring
+
+guiObjectCollector = PStatCollector("Client::GuiObjects")
+
+
 class DirectGuiBase(DirectObject.DirectObject):
+    """Base class of all DirectGUI widgets."""
+
     def __init__(self):
         # Default id of all gui object, subclasses should override this
         self.guiId = 'guiObject'
diff --git a/direct/src/gui/DirectGuiGlobals.py b/direct/src/gui/DirectGuiGlobals.py
index d71c97593d..96519fd9fc 100644
--- a/direct/src/gui/DirectGuiGlobals.py
+++ b/direct/src/gui/DirectGuiGlobals.py
@@ -1,12 +1,10 @@
-"""Undocumented Module"""
-
-__all__ = []
-
-
 """
 Global definitions used by Direct Gui Classes and handy constants
 that can be used during widget construction
 """
+
+__all__ = []
+
 from panda3d.core import *
 
 defaultFont = None
diff --git a/direct/src/gui/DirectLabel.py b/direct/src/gui/DirectLabel.py
index 5cb2932900..bc1328ded7 100644
--- a/direct/src/gui/DirectLabel.py
+++ b/direct/src/gui/DirectLabel.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Contains the DirectLabel class."""
 
 __all__ = ['DirectLabel']
 
diff --git a/direct/src/gui/DirectOptionMenu.py b/direct/src/gui/DirectOptionMenu.py
index e2432a5512..40d48f7672 100644
--- a/direct/src/gui/DirectOptionMenu.py
+++ b/direct/src/gui/DirectOptionMenu.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Implements a pop-up menu containing multiple clickable options."""
 
 __all__ = ['DirectOptionMenu']
 
diff --git a/direct/src/gui/DirectRadioButton.py b/direct/src/gui/DirectRadioButton.py
index 8044e81295..f6543d1e8f 100755
--- a/direct/src/gui/DirectRadioButton.py
+++ b/direct/src/gui/DirectRadioButton.py
@@ -1,4 +1,7 @@
-"""Undocumented Module"""
+"""A DirectRadioButton is a type of button that, similar to a
+DirectCheckButton, has a separate indicator and can be toggled between
+two states.  However, only one DirectRadioButton in a group can be enabled
+at a particular time."""
 
 __all__ = ['DirectRadioButton']
 
diff --git a/direct/src/gui/DirectScrollBar.py b/direct/src/gui/DirectScrollBar.py
index 8493547e0d..d56385163b 100644
--- a/direct/src/gui/DirectScrollBar.py
+++ b/direct/src/gui/DirectScrollBar.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Defines the DirectScrollBar class."""
 
 __all__ = ['DirectScrollBar']
 
diff --git a/direct/src/gui/DirectScrolledFrame.py b/direct/src/gui/DirectScrolledFrame.py
index 6a7be7cabf..c44bc7a0fb 100644
--- a/direct/src/gui/DirectScrolledFrame.py
+++ b/direct/src/gui/DirectScrolledFrame.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Contains the DirectScrolledFrame class."""
 
 __all__ = ['DirectScrolledFrame']
 
diff --git a/direct/src/gui/DirectScrolledList.py b/direct/src/gui/DirectScrolledList.py
index d17023d545..a89b691576 100644
--- a/direct/src/gui/DirectScrolledList.py
+++ b/direct/src/gui/DirectScrolledList.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Contains the DirectScrolledList class."""
 
 __all__ = ['DirectScrolledListItem', 'DirectScrolledList']
 
diff --git a/direct/src/gui/DirectSlider.py b/direct/src/gui/DirectSlider.py
index 73f5410e49..507c13b5a8 100644
--- a/direct/src/gui/DirectSlider.py
+++ b/direct/src/gui/DirectSlider.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Defines the DirectSlider class."""
 
 __all__ = ['DirectSlider']
 
diff --git a/direct/src/gui/DirectWaitBar.py b/direct/src/gui/DirectWaitBar.py
index a8eb9a56cc..ff3f554fee 100644
--- a/direct/src/gui/DirectWaitBar.py
+++ b/direct/src/gui/DirectWaitBar.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Contains the DirectWaitBar class, a progress bar widget."""
 
 __all__ = ['DirectWaitBar']
 
diff --git a/direct/src/gui/__init__.py b/direct/src/gui/__init__.py
index e69de29bb2..5cc1895b62 100644
--- a/direct/src/gui/__init__.py
+++ b/direct/src/gui/__init__.py
@@ -0,0 +1,12 @@
+"""
+This package contains the DirectGui system, a set of classes
+responsible for drawing graphical widgets to the 2-D scene graph.
+
+It is based on the lower-level PGui system, which is implemented in
+C++.
+
+For convenience, all of the DirectGui widgets may be imported from a
+single module as follows::
+
+   from direct.gui.DirectGui import *
+"""
diff --git a/direct/src/interval/IntervalGlobal.py b/direct/src/interval/IntervalGlobal.py
index 903f92d14f..41ee6444f7 100644
--- a/direct/src/interval/IntervalGlobal.py
+++ b/direct/src/interval/IntervalGlobal.py
@@ -1,4 +1,7 @@
-"""IntervalGlobal module"""
+"""
+This module imports all of the other interval modules, to provide a
+single convenient module from which all interval types can be imported.
+"""
 
 # In this unusual case, I'm not going to declare __all__,
 # since the purpose of this module is to add up the contributions
diff --git a/direct/src/interval/IntervalManager.py b/direct/src/interval/IntervalManager.py
index 0e909ceeb8..a9a44a3bf0 100644
--- a/direct/src/interval/IntervalManager.py
+++ b/direct/src/interval/IntervalManager.py
@@ -1,4 +1,5 @@
-"""Undocumented Module"""
+"""Defines the IntervalManager class as well as the global instance of
+this class, ivalMgr."""
 
 __all__ = ['IntervalManager', 'ivalMgr']
 
@@ -136,6 +137,5 @@ class IntervalManager(CIntervalManager):
         assert self.ivals[index] == None or self.ivals[index] == interval
         self.ivals[index] = interval
 
-# The global IntervalManager object.
+#: The global IntervalManager object.
 ivalMgr = IntervalManager(1)
-
diff --git a/direct/src/interval/MetaInterval.py b/direct/src/interval/MetaInterval.py
index dc83f3587c..fd379280a7 100644
--- a/direct/src/interval/MetaInterval.py
+++ b/direct/src/interval/MetaInterval.py
@@ -1,4 +1,7 @@
-"""Undocumented Module"""
+"""
+This module defines the various "meta intervals", which execute other
+intervals either in parallel or in a specified sequential order.
+"""
 
 __all__ = ['MetaInterval', 'Sequence', 'Parallel', 'ParallelEndTogether', 'Track']
 
diff --git a/direct/src/interval/ParticleInterval.py b/direct/src/interval/ParticleInterval.py
index c373af7542..b5a3b09b73 100644
--- a/direct/src/interval/ParticleInterval.py
+++ b/direct/src/interval/ParticleInterval.py
@@ -1,11 +1,9 @@
-"""Undocumented Module"""
-
-__all__ = ['ParticleInterval']
-
 """
 Contains the ParticleInterval class
 """
 
+__all__ = ['ParticleInterval']
+
 from panda3d.core import *
 from panda3d.direct import *
 from direct.directnotify.DirectNotifyGlobal import directNotify
diff --git a/direct/src/interval/TestInterval.py b/direct/src/interval/TestInterval.py
index 82a04b604e..6a13cce4f2 100755
--- a/direct/src/interval/TestInterval.py
+++ b/direct/src/interval/TestInterval.py
@@ -1,11 +1,9 @@
-"""Undocumented Module"""
+"""
+Contains the TestInterval class
+"""
 
 __all__ = ['TestInterval']
 
-"""
-Contains the ParticleInterval class
-"""
-
 from panda3d.core import *
 from panda3d.direct import *
 from direct.directnotify.DirectNotifyGlobal import directNotify
diff --git a/direct/src/interval/__init__.py b/direct/src/interval/__init__.py
index e69de29bb2..5f3e8e4332 100644
--- a/direct/src/interval/__init__.py
+++ b/direct/src/interval/__init__.py
@@ -0,0 +1,12 @@
+"""
+This package contains the Python implementation of the interval system,
+which is a mechanism for playing back scripted actions.  A range of
+interval types has been defined to automate motion, animation, sounds,
+color, function calls, as well as other intervals and arbitrary
+properties.
+
+All interval types can be conveniently imported from the
+:mod:`.IntervalGlobal` module::
+
+   from direct.interval.IntervalGlobal import *
+"""
diff --git a/direct/src/motiontrail/__init__.py b/direct/src/motiontrail/__init__.py
index e69de29bb2..d50bc43be3 100644
--- a/direct/src/motiontrail/__init__.py
+++ b/direct/src/motiontrail/__init__.py
@@ -0,0 +1,3 @@
+"""
+This package contains only the :class:`.MotionTrail` class.
+"""
diff --git a/direct/src/p3d/AppRunner.py b/direct/src/p3d/AppRunner.py
index 4a59e20de6..aae03754e6 100644
--- a/direct/src/p3d/AppRunner.py
+++ b/direct/src/p3d/AppRunner.py
@@ -1,12 +1,15 @@
-
 """
-
 This module is intended to be compiled into the Panda3D runtime
 distributable, to execute a packaged p3d application, but it can also
 be run directly via the Python interpreter (if the current Panda3D and
 Python versions match the version expected by the application).  See
 runp3d.py for a command-line tool to invoke this module.
 
+The global AppRunner instance may be imported as follows::
+
+   from direct.showbase.AppRunnerGlobal import appRunner
+
+This will be None if Panda was not run from the runtime environment.
 """
 
 __all__ = ["AppRunner", "dummyAppRunner", "ArgumentError"]
diff --git a/direct/src/p3d/__init__.py b/direct/src/p3d/__init__.py
index e69de29bb2..e6ab93b09d 100644
--- a/direct/src/p3d/__init__.py
+++ b/direct/src/p3d/__init__.py
@@ -0,0 +1,4 @@
+"""
+This package provides the Python interface to functionality relating to
+the Panda3D Runtime environment.
+"""
diff --git a/direct/src/particles/__init__.py b/direct/src/particles/__init__.py
index e69de29bb2..d3525ee464 100644
--- a/direct/src/particles/__init__.py
+++ b/direct/src/particles/__init__.py
@@ -0,0 +1,7 @@
+"""
+This package contains the high-level Python interface to the particle
+system.
+
+Also see the :mod:`panda3d.physics` module, which contains the C++
+implementation of the particle system.
+"""
diff --git a/direct/src/showbase/AppRunnerGlobal.py b/direct/src/showbase/AppRunnerGlobal.py
index 9e4b083f25..2ab5c0ccf9 100644
--- a/direct/src/showbase/AppRunnerGlobal.py
+++ b/direct/src/showbase/AppRunnerGlobal.py
@@ -6,4 +6,6 @@ This is needed for apps that start themselves by importing
 DirectStart; it provides a place for these apps to look for
 the AppRunner at startup. """
 
+#: Contains the global AppRunner instance, or None if this application
+#: was not run from the runtime environment.
 appRunner = None
diff --git a/direct/src/showbase/Audio3DManager.py b/direct/src/showbase/Audio3DManager.py
index e9cdb59eb8..07407c822b 100644
--- a/direct/src/showbase/Audio3DManager.py
+++ b/direct/src/showbase/Audio3DManager.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Contains the Audio3DManager class."""
 
 __all__ = ['Audio3DManager']
 
diff --git a/direct/src/showbase/BufferViewer.py b/direct/src/showbase/BufferViewer.py
index c2a7f86049..48dff3a1ea 100644
--- a/direct/src/showbase/BufferViewer.py
+++ b/direct/src/showbase/BufferViewer.py
@@ -1,4 +1,6 @@
-"""Undocumented Module"""
+"""Contains the BufferViewer class, which is used as a debugging aid
+when debugging render-to-texture effects.  It shows different views at
+the bottom of the screen showing the various render targets."""
 
 __all__ = ['BufferViewer']
 
diff --git a/direct/src/showbase/BulletinBoard.py b/direct/src/showbase/BulletinBoard.py
index c46eb0ff0e..5b1cdd71a0 100755
--- a/direct/src/showbase/BulletinBoard.py
+++ b/direct/src/showbase/BulletinBoard.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Contains the BulletinBoard class."""
 
 __all__ = ['BulletinBoard']
 
diff --git a/direct/src/showbase/BulletinBoardWatcher.py b/direct/src/showbase/BulletinBoardWatcher.py
index da2cb8dd63..efc75b43ac 100755
--- a/direct/src/showbase/BulletinBoardWatcher.py
+++ b/direct/src/showbase/BulletinBoardWatcher.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Contains the BulletinBoardWatcher class."""
 
 __all__ = ['BulletinBoardWatcher']
 
diff --git a/direct/src/showbase/DirectObject.py b/direct/src/showbase/DirectObject.py
index 22d846bc3e..9106637134 100644
--- a/direct/src/showbase/DirectObject.py
+++ b/direct/src/showbase/DirectObject.py
@@ -1,4 +1,5 @@
-"""Undocumented Module"""
+"""Defines the DirectObject class, a convenient class to inherit from if the
+object needs to be able to respond to events."""
 
 __all__ = ['DirectObject']
 
diff --git a/direct/src/showbase/EventGroup.py b/direct/src/showbase/EventGroup.py
index baf26193f4..6385761ca4 100755
--- a/direct/src/showbase/EventGroup.py
+++ b/direct/src/showbase/EventGroup.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""This module defines the EventGroup class."""
 
 __all__ = ['EventGroup']
 
diff --git a/direct/src/showbase/EventManager.py b/direct/src/showbase/EventManager.py
index 35616f6002..af8bd1c91a 100644
--- a/direct/src/showbase/EventManager.py
+++ b/direct/src/showbase/EventManager.py
@@ -1,4 +1,5 @@
-"""Undocumented Module"""
+"""Contains the EventManager class.  See :mod:`.EventManagerGlobal` for the
+global eventMgr instance."""
 
 __all__ = ['EventManager']
 
diff --git a/direct/src/showbase/EventManagerGlobal.py b/direct/src/showbase/EventManagerGlobal.py
index 9e7000ed51..73a35b8ba5 100644
--- a/direct/src/showbase/EventManagerGlobal.py
+++ b/direct/src/showbase/EventManagerGlobal.py
@@ -1,7 +1,8 @@
-"""Undocumented Module"""
+"""Contains the global :class:`.EventManager` instance."""
 
 __all__ = ['eventMgr']
 
 from . import EventManager
 
+#: The global event manager.
 eventMgr = EventManager.EventManager()
diff --git a/direct/src/showbase/Factory.py b/direct/src/showbase/Factory.py
index bff33dd931..0abd217c07 100755
--- a/direct/src/showbase/Factory.py
+++ b/direct/src/showbase/Factory.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Contains the Factory class."""
 
 __all__ = ['Factory']
 
diff --git a/direct/src/showbase/FindCtaPaths.py b/direct/src/showbase/FindCtaPaths.py
index a530778715..4832400b46 100755
--- a/direct/src/showbase/FindCtaPaths.py
+++ b/direct/src/showbase/FindCtaPaths.py
@@ -1,7 +1,3 @@
-"""Undocumented Module"""
-
-__all__ = ['deCygwinify', 'getPaths']
-
 """This module is used only by the VR Studio programmers who are using
 the ctattach tools.  It is imported before any other package, and its
 job is to figure out the correct paths to each of the packages.
@@ -10,6 +6,8 @@ This module is not needed if you are not using ctattach; in this case
 all of the Panda packages will be collected under a common directory,
 which you will presumably have already on your PYTHONPATH. """
 
+__all__ = ['deCygwinify', 'getPaths']
+
 import os
 import sys
 
diff --git a/direct/src/showbase/Finder.py b/direct/src/showbase/Finder.py
index f7c619da91..129bcb4dc6 100644
--- a/direct/src/showbase/Finder.py
+++ b/direct/src/showbase/Finder.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Contains various utility functions."""
 
 __all__ = ['findClass', 'rebindClass', 'copyFuncs', 'replaceMessengerFunc', 'replaceTaskMgrFunc', 'replaceStateFunc', 'replaceCRFunc', 'replaceAIRFunc', 'replaceIvalFunc']
 
diff --git a/direct/src/showbase/GarbageReport.py b/direct/src/showbase/GarbageReport.py
index db91df0c47..7d268bf450 100755
--- a/direct/src/showbase/GarbageReport.py
+++ b/direct/src/showbase/GarbageReport.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Contains utility classes for debugging memory leaks."""
 
 __all__ = ['FakeObject', '_createGarbage', 'GarbageReport', 'GarbageLogger']
 
diff --git a/direct/src/showbase/Messenger.py b/direct/src/showbase/Messenger.py
index 92d2014503..09ceb9cd0a 100644
--- a/direct/src/showbase/Messenger.py
+++ b/direct/src/showbase/Messenger.py
@@ -1,4 +1,5 @@
-"""Undocumented Module"""
+"""This defines the Messenger class, which is responsible for most of the
+event handling that happens on the Python side."""
 
 __all__ = ['Messenger']
 
diff --git a/direct/src/showbase/MirrorDemo.py b/direct/src/showbase/MirrorDemo.py
index e2a77dbf82..b44106db47 100755
--- a/direct/src/showbase/MirrorDemo.py
+++ b/direct/src/showbase/MirrorDemo.py
@@ -1,7 +1,3 @@
-"""Undocumented Module"""
-
-__all__ = ['setupMirror', 'showFrustum']
-
 """This file demonstrates one way to create a mirror effect in Panda.
 Call setupMirror() to create a mirror in the world that reflects
 everything in front of it.
@@ -23,6 +19,8 @@ surface are possible, like a funhouse mirror.  However, the reflection
 itself is always basically planar; for more accurate convex
 reflections, you will need to use a sphere map or a cube map."""
 
+__all__ = ['setupMirror', 'showFrustum']
+
 from panda3d.core import *
 from direct.task import Task
 
diff --git a/direct/src/showbase/ObjectPool.py b/direct/src/showbase/ObjectPool.py
index 4b0c0a0731..e5970803ab 100755
--- a/direct/src/showbase/ObjectPool.py
+++ b/direct/src/showbase/ObjectPool.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Contains the ObjectPool utility class."""
 
 __all__ = ['Diff', 'ObjectPool']
 
diff --git a/direct/src/showbase/ObjectReport.py b/direct/src/showbase/ObjectReport.py
index b860932d2d..a0fcce7168 100755
--- a/direct/src/showbase/ObjectReport.py
+++ b/direct/src/showbase/ObjectReport.py
@@ -1,4 +1,13 @@
-"""Undocumented Module"""
+"""
+>>> from direct.showbase import ObjectReport
+
+>>> o=ObjectReport.ObjectReport('baseline')
+>>> run()
+...
+
+>>> o2=ObjectReport.ObjectReport('')
+>>> o.diff(o2)
+"""
 
 __all__ = ['ExclusiveObjectPool', 'ObjectReport']
 
@@ -13,17 +22,6 @@ if sys.version_info >= (3, 0):
 else:
     import __builtin__ as builtins
 
-"""
->>> from direct.showbase import ObjectReport
-
->>> o=ObjectReport.ObjectReport('baseline')
->>> run()
-...
-
->>> o2=ObjectReport.ObjectReport('')
->>> o.diff(o2)
-"""
-
 class ExclusiveObjectPool(DirectObject.DirectObject):
     # ObjectPool specialization that excludes particular objects
     # IDs of objects to globally exclude from reporting
diff --git a/direct/src/showbase/OnScreenDebug.py b/direct/src/showbase/OnScreenDebug.py
index ba24b0637a..1a5756c078 100755
--- a/direct/src/showbase/OnScreenDebug.py
+++ b/direct/src/showbase/OnScreenDebug.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Contains the OnScreenDebug class."""
 
 __all__ = ['OnScreenDebug']
 
diff --git a/direct/src/showbase/Pool.py b/direct/src/showbase/Pool.py
index ddcc80a32d..5c1782d629 100755
--- a/direct/src/showbase/Pool.py
+++ b/direct/src/showbase/Pool.py
@@ -1,9 +1,4 @@
-"""Undocumented Module"""
-
-__all__ = ['Pool']
-
 """
-
 Pool is a collection of python objects that you can checkin and
 checkout. This is useful for a cache of objects that are expensive to load
 and can be reused over and over, like splashes on cannonballs, or
@@ -12,12 +7,16 @@ or be the same type.
 
 Internally the pool is implemented with 2 lists, free items and used items.
 
-p = Pool([1, 2, 3, 4, 5])
-x = p.checkout()
-p.checkin(x)
+Example::
+
+   p = Pool([1, 2, 3, 4, 5])
+   x = p.checkout()
+   p.checkin(x)
 
 """
 
+__all__ = ['Pool']
+
 
 from direct.directnotify import DirectNotifyGlobal
 
@@ -116,5 +115,3 @@ class Pool:
 
     def __repr__(self):
         return "free = %s\nused = %s" % (self.__free, self.__used)
-
-
diff --git a/direct/src/showbase/SfxPlayer.py b/direct/src/showbase/SfxPlayer.py
index 2fb97eae32..4f139a89c9 100644
--- a/direct/src/showbase/SfxPlayer.py
+++ b/direct/src/showbase/SfxPlayer.py
@@ -1,4 +1,5 @@
-"""Undocumented Module"""
+"""Contains the SfxPlayer class, a thin utility class for playing sounds at
+a particular location."""
 
 __all__ = ['SfxPlayer']
 
@@ -95,6 +96,3 @@ class SfxPlayer:
             if node is not None:
                 finalVolume *= node.getNetAudioVolume()
             sfx.setVolume(finalVolume)
-
-
-
diff --git a/direct/src/showbase/ShadowDemo.py b/direct/src/showbase/ShadowDemo.py
index 78f9d33dd0..daadd58c11 100755
--- a/direct/src/showbase/ShadowDemo.py
+++ b/direct/src/showbase/ShadowDemo.py
@@ -1,8 +1,3 @@
-"""Undocumented Module"""
-
-__all__ = ['ShadowCaster', 'avatarShadow', 'piratesAvatarShadow', 'arbitraryShadow']
-
-
 """Create a cheesy shadow effect by rendering the view of an
 object (e.g. the local avatar) from a special camera as seen from
 above (as if from the sun), using a solid gray foreground and a
@@ -14,6 +9,8 @@ multitexture rendering techniques.  It's not a particularly great
 way to do shadows.
 """
 
+__all__ = ['ShadowCaster', 'avatarShadow', 'piratesAvatarShadow', 'arbitraryShadow']
+
 from panda3d.core import *
 from direct.task import Task
 
diff --git a/direct/src/showbase/ShadowPlacer.py b/direct/src/showbase/ShadowPlacer.py
index 80826926f7..845bb5e66e 100755
--- a/direct/src/showbase/ShadowPlacer.py
+++ b/direct/src/showbase/ShadowPlacer.py
@@ -1,7 +1,3 @@
-"""Undocumented Module"""
-
-__all__ = ['ShadowPlacer']
-
 """
 ShadowPlacer.py places a shadow.
 
@@ -10,6 +6,8 @@ Or it may do that later, right now it puts a node on the surface under
 the its parent node.
 """
 
+__all__ = ['ShadowPlacer']
+
 from direct.controls.ControlManager import CollisionHandlerRayStart
 from direct.directnotify import DirectNotifyGlobal
 from panda3d.core import *
diff --git a/direct/src/showbase/TaskThreaded.py b/direct/src/showbase/TaskThreaded.py
index b320e84453..a6634cd751 100755
--- a/direct/src/showbase/TaskThreaded.py
+++ b/direct/src/showbase/TaskThreaded.py
@@ -1,10 +1,13 @@
-"""Undocumented Module"""
+"""Contains the TaskThreaded and TaskThread classes."""
 
 __all__ = ['TaskThreaded', 'TaskThread']
 
 from direct.directnotify.DirectNotifyGlobal import directNotify
 from direct.task import Task
 
+from .PythonUtil import SerialNumGen
+
+
 class TaskThreaded:
     """ derive from this if you need to do a bunch of CPU-intensive
     processing and you don't want to hang up the show. Lets you break
diff --git a/direct/src/showbase/ThreeUpShow.py b/direct/src/showbase/ThreeUpShow.py
index 6449033c50..7e042c7f39 100644
--- a/direct/src/showbase/ThreeUpShow.py
+++ b/direct/src/showbase/ThreeUpShow.py
@@ -1,4 +1,5 @@
-"""Undocumented Module"""
+"""ThreeUpShow is a variant of ShowBase that defines three cameras covering
+different parts of the window."""
 
 __all__ = ['ThreeUpShow']
 
diff --git a/direct/src/showbase/Transitions.py b/direct/src/showbase/Transitions.py
index c60ac8c09e..9e34756404 100644
--- a/direct/src/showbase/Transitions.py
+++ b/direct/src/showbase/Transitions.py
@@ -1,4 +1,6 @@
-"""Undocumented Module"""
+"""This module defines various transition effects that can be used to
+graphically transition between two scenes, such as by fading the screen to
+a particular color."""
 
 __all__ = ['Transitions']
 
diff --git a/direct/src/showbase/VerboseImport.py b/direct/src/showbase/VerboseImport.py
index 56efc33b23..9c61783ea5 100644
--- a/direct/src/showbase/VerboseImport.py
+++ b/direct/src/showbase/VerboseImport.py
@@ -1,4 +1,7 @@
-"""Undocumented Module"""
+"""
+This module hooks into Python's import mechanism to print out all imports to
+the standard output as they happen.
+"""
 
 __all__ = []
 
diff --git a/direct/src/showutil/pfreeze.py b/direct/src/showutil/pfreeze.py
index 04397d31d9..2c2827e051 100755
--- a/direct/src/showutil/pfreeze.py
+++ b/direct/src/showutil/pfreeze.py
@@ -13,11 +13,11 @@ Python code into a standalone executable.  It also uses Python's
 built-in modulefinder module, which it uses to find all of the modules
 imported directly or indirectly by the original startfile.py.
 
-Usage:
+Usage::
 
   pfreeze.py [opts] [startfile]
 
-Options:
+Options::
 
   -o output
      Specifies the name of the resulting executable file to produce.
@@ -67,88 +67,95 @@ def usage(code, msg = ''):
     sys.stderr.write(str(msg) + '\n')
     sys.exit(code)
 
-# We're not protecting the next part under a __name__ == __main__
-# check, just so we can import this file directly in ppython.cxx.
 
-freezer = FreezeTool.Freezer()
+def main(args=None):
+    if args is None:
+        args = sys.argv[1:]
 
-basename = None
-addStartupModules = False
+    freezer = FreezeTool.Freezer()
 
-try:
-    opts, args = getopt.getopt(sys.argv[1:], 'o:i:x:p:P:slkh')
-except getopt.error as msg:
-    usage(1, msg)
+    basename = None
+    addStartupModules = False
 
-for opt, arg in opts:
-    if opt == '-o':
-        basename = arg
-    elif opt == '-i':
-        for module in arg.split(','):
-            freezer.addModule(module)
-    elif opt == '-x':
-        for module in arg.split(','):
-            freezer.excludeModule(module)
-    elif opt == '-p':
-        for module in arg.split(','):
-            freezer.handleCustomPath(module)
-    elif opt == '-P':
-        sys.path.append(arg)
-    elif opt == '-s':
-        addStartupModules = True
-    elif opt == '-l':
-        freezer.linkExtensionModules = True
-    elif opt == '-k':
-        freezer.keepTemporaryFiles = True
-    elif opt == '-h':
-        usage(0)
+    try:
+        opts, args = getopt.getopt(args, 'o:i:x:p:P:slkh')
+    except getopt.error as msg:
+        usage(1, msg)
+
+    for opt, arg in opts:
+        if opt == '-o':
+            basename = arg
+        elif opt == '-i':
+            for module in arg.split(','):
+                freezer.addModule(module)
+        elif opt == '-x':
+            for module in arg.split(','):
+                freezer.excludeModule(module)
+        elif opt == '-p':
+            for module in arg.split(','):
+                freezer.handleCustomPath(module)
+        elif opt == '-P':
+            sys.path.append(arg)
+        elif opt == '-s':
+            addStartupModules = True
+        elif opt == '-l':
+            freezer.linkExtensionModules = True
+        elif opt == '-k':
+            freezer.keepTemporaryFiles = True
+        elif opt == '-h':
+            usage(0)
+        else:
+            print('illegal option: ' + flag)
+            sys.exit(1)
+
+    if not basename:
+        usage(1, 'You did not specify an output file.')
+
+    if len(args) > 1:
+        usage(1, 'Only one main file may be specified.')
+
+    outputType = 'exe'
+    bl = basename.lower()
+    if bl.endswith('.mf'):
+        outputType = 'mf'
+    elif bl.endswith('.c'):
+        outputType = 'c'
+    elif bl.endswith('.dll') or bl.endswith('.pyd') or bl.endswith('.so'):
+        basename = os.path.splitext(basename)[0]
+        outputType = 'dll'
+    elif bl.endswith('.exe'):
+        basename = os.path.splitext(basename)[0]
+
+    compileToExe = False
+    if args:
+        startfile = args[0]
+        startmod = startfile
+        if startfile.endswith('.py') or startfile.endswith('.pyw') or \
+        startfile.endswith('.pyc') or startfile.endswith('.pyo'):
+            startmod = os.path.splitext(startfile)[0]
+
+        if outputType == 'dll' or outputType == 'c':
+            freezer.addModule(startmod, filename = startfile)
+        else:
+            freezer.addModule('__main__', filename = startfile)
+            compileToExe = True
+            addStartupModules = True
+
+    elif outputType == 'exe':
+        # We must have a main module when making an executable.
+        usage(1, 'A main file needs to be specified when creating an executable.')
+
+    freezer.done(addStartupModules = addStartupModules)
+
+    if outputType == 'mf':
+        freezer.writeMultifile(basename)
+    elif outputType == 'c':
+        freezer.writeCode(basename)
     else:
-        print('illegal option: ' + flag)
-        sys.exit(1)
+        freezer.generateCode(basename, compileToExe = compileToExe)
 
-if not basename:
-    usage(1, 'You did not specify an output file.')
+    return 0
 
-if len(args) > 1:
-    usage(1, 'Only one main file may be specified.')
-
-outputType = 'exe'
-bl = basename.lower()
-if bl.endswith('.mf'):
-    outputType = 'mf'
-elif bl.endswith('.c'):
-    outputType = 'c'
-elif bl.endswith('.dll') or bl.endswith('.pyd') or bl.endswith('.so'):
-    basename = os.path.splitext(basename)[0]
-    outputType = 'dll'
-elif bl.endswith('.exe'):
-    basename = os.path.splitext(basename)[0]
-
-compileToExe = False
-if args:
-    startfile = args[0]
-    startmod = startfile
-    if startfile.endswith('.py') or startfile.endswith('.pyw') or \
-       startfile.endswith('.pyc') or startfile.endswith('.pyo'):
-        startmod = os.path.splitext(startfile)[0]
-
-    if outputType == 'dll' or outputType == 'c':
-        freezer.addModule(startmod, filename = startfile)
-    else:
-        freezer.addModule('__main__', filename = startfile)
-        compileToExe = True
-        addStartupModules = True
-
-elif outputType == 'exe':
-    # We must have a main module when making an executable.
-    usage(1, 'A main file needs to be specified when creating an executable.')
-
-freezer.done(addStartupModules = addStartupModules)
-
-if outputType == 'mf':
-    freezer.writeMultifile(basename)
-elif outputType == 'c':
-    freezer.writeCode(basename)
-else:
-    freezer.generateCode(basename, compileToExe = compileToExe)
 
+if __name__ == '__main__':
+    sys.exit(main())
diff --git a/direct/src/stdpy/__init__.py b/direct/src/stdpy/__init__.py
index e69de29bb2..9e4739449c 100644
--- a/direct/src/stdpy/__init__.py
+++ b/direct/src/stdpy/__init__.py
@@ -0,0 +1,5 @@
+"""
+This package contains various modules that provide a drop-in substitute
+for some of the built-in Python modules.  These substitutes make better
+use of Panda3D's virtual file system and threading system.
+"""
diff --git a/direct/src/task/TaskManagerGlobal.py b/direct/src/task/TaskManagerGlobal.py
index 60587d7a4f..792938cfc4 100644
--- a/direct/src/task/TaskManagerGlobal.py
+++ b/direct/src/task/TaskManagerGlobal.py
@@ -4,4 +4,5 @@ __all__ = ['taskMgr']
 
 from . import Task
 
+#: The global task manager.
 taskMgr = Task.TaskManager()
diff --git a/direct/src/task/TaskTester.py b/direct/src/task/TaskTester.py
index 25437f9b6b..cbe8cd0bd7 100755
--- a/direct/src/task/TaskTester.py
+++ b/direct/src/task/TaskTester.py
@@ -24,7 +24,8 @@ def taskCallback(task):
     spawnNewTask()
     return Task.done
 
-taskMgr.removeTasksMatching("taskTester*")
+if __name__ == '__main__':
+    taskMgr.removeTasksMatching("taskTester*")
 
-for i in range(numTasks):
-    spawnNewTask()
+    for i in range(numTasks):
+        spawnNewTask()
diff --git a/direct/src/task/Timer.py b/direct/src/task/Timer.py
index be7957183c..47d5041de9 100644
--- a/direct/src/task/Timer.py
+++ b/direct/src/task/Timer.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Contains the Timer class."""
 
 __all__ = ['Timer']
 
diff --git a/direct/src/task/__init__.py b/direct/src/task/__init__.py
index e69de29bb2..40a5246131 100644
--- a/direct/src/task/__init__.py
+++ b/direct/src/task/__init__.py
@@ -0,0 +1,8 @@
+"""
+This package contains the Python interface to the task system, which
+manages scheduled functions that are executed at designated intervals.
+
+The global task manager object can be imported as a singleton::
+
+   from direct.task.TaskManagerGlobal import taskMgr
+"""
diff --git a/direct/src/tkpanels/NotifyPanel.py b/direct/src/tkpanels/NotifyPanel.py
index 9712903f7a..f13e7d92c6 100644
--- a/direct/src/tkpanels/NotifyPanel.py
+++ b/direct/src/tkpanels/NotifyPanel.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Contains the NotifyPanel class."""
 
 __all__ = ['NotifyPanel']
 
diff --git a/direct/src/tkwidgets/SceneGraphExplorer.py b/direct/src/tkwidgets/SceneGraphExplorer.py
index 7e39dbeac1..256f226f46 100644
--- a/direct/src/tkwidgets/SceneGraphExplorer.py
+++ b/direct/src/tkwidgets/SceneGraphExplorer.py
@@ -1,4 +1,7 @@
-"""Undocumented Module"""
+"""This module defines a widget used to display a graphical overview of the
+scene graph using the tkinter GUI system.
+
+Requires Pmw."""
 
 __all__ = ['SceneGraphExplorer', 'SceneGraphExplorerItem', 'explore']
 
diff --git a/direct/src/tkwidgets/Tree.py b/direct/src/tkwidgets/Tree.py
index e3e49b925f..ff8a273965 100644
--- a/direct/src/tkwidgets/Tree.py
+++ b/direct/src/tkwidgets/Tree.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Defines tree widgets for the tkinter GUI system."""
 
 __all__ = ['TreeNode', 'TreeItem']
 
diff --git a/direct/src/tkwidgets/WidgetPropertiesDialog.py b/direct/src/tkwidgets/WidgetPropertiesDialog.py
index 0693a885d1..584e45620c 100644
--- a/direct/src/tkwidgets/WidgetPropertiesDialog.py
+++ b/direct/src/tkwidgets/WidgetPropertiesDialog.py
@@ -1,4 +1,4 @@
-"""Undocumented Module"""
+"""Contains the WidgetPropertiesDialog class."""
 
 __all__ = ['WidgetPropertiesDialog']
 
diff --git a/dtool/src/dtoolbase/typedObject.h b/dtool/src/dtoolbase/typedObject.h
index 789e47110c..cc963b0fac 100644
--- a/dtool/src/dtoolbase/typedObject.h
+++ b/dtool/src/dtoolbase/typedObject.h
@@ -97,6 +97,8 @@ PUBLISHED:
 
   // Derived classes should override this function to return get_class_type().
   virtual TypeHandle get_type() const=0;
+
+  // Returns the TypeHandle representing this object's type.
   MAKE_PROPERTY(type, get_type);
 
   INLINE int get_type_index() const;
diff --git a/dtool/src/interrogate/interrogateBuilder.cxx b/dtool/src/interrogate/interrogateBuilder.cxx
index c7ed2a056f..a36b370942 100644
--- a/dtool/src/interrogate/interrogateBuilder.cxx
+++ b/dtool/src/interrogate/interrogateBuilder.cxx
@@ -1966,6 +1966,10 @@ get_make_property(CPPMakeProperty *make_property, CPPStructType *struct_type, CP
   // See if there happens to be a comment before the MAKE_PROPERTY macro.
   if (make_property->_leading_comment != (CPPCommentBlock *)NULL) {
     iproperty._comment = trim_blanks(make_property->_leading_comment->_comment);
+
+  } else if (getter->_leading_comment != (CPPCommentBlock *)NULL) {
+    // Take the comment from the getter.
+    iproperty._comment = trim_blanks(getter->_leading_comment->_comment);
   }
 
   // Now look for setters.
diff --git a/makepanda/makewheel.py b/makepanda/makewheel.py
index 56fb43133e..71ec67a269 100644
--- a/makepanda/makewheel.py
+++ b/makepanda/makewheel.py
@@ -551,6 +551,7 @@ def makewheel(version, output_dir, platform=default_platform):
     # Add a panda3d-tools directory containing the executables.
     entry_points = '[console_scripts]\n'
     entry_points += 'eggcacher = direct.directscripts.eggcacher:main\n'
+    entry_points += 'pfreeze = direct.showutil.pfreeze:main\n'
     tools_init = ''
     for file in os.listdir(bin_dir):
         basename = os.path.splitext(file)[0]
diff --git a/panda/src/pgraph/lightRampAttrib.cxx b/panda/src/pgraph/lightRampAttrib.cxx
index 78ba5aaef1..38ed81affe 100644
--- a/panda/src/pgraph/lightRampAttrib.cxx
+++ b/panda/src/pgraph/lightRampAttrib.cxx
@@ -51,8 +51,14 @@ make_identity() {
 /**
  * Constructs a new LightRampAttrib object.  This causes the luminance of the
  * diffuse lighting contribution to be quantized using a single threshold:
- * @code if (original_luminance > threshold0) { luminance = level0; } else {
- * luminance = 0.0; } @endcode
+ *
+ * @code
+ * if (original_luminance > threshold0) {
+ *   luminance = level0;
+ * } else {
+ *   luminance = 0.0;
+ * }
+ * @endcode
  */
 CPT(RenderAttrib) LightRampAttrib::
 make_single_threshold(PN_stdfloat thresh0, PN_stdfloat val0) {
@@ -65,10 +71,17 @@ make_single_threshold(PN_stdfloat thresh0, PN_stdfloat val0) {
 
 /**
  * Constructs a new LightRampAttrib object.  This causes the luminance of the
- * diffuse lighting contribution to be quantized using two thresholds: @code
- * if (original_luminance > threshold1) { luminance = level1; } else if
- * (original_luminance > threshold0) { luminance = level0; } else { luminance
- * = 0.0; } @endcode
+ * diffuse lighting contribution to be quantized using two thresholds:
+ *
+ * @code
+ * if (original_luminance > threshold1) {
+ *   luminance = level1;
+ * } else if (original_luminance > threshold0) {
+ *   luminance = level0;
+ * } else {
+ *   luminance = 0.0;
+ * }
+ * @endcode
  */
 CPT(RenderAttrib) LightRampAttrib::
 make_double_threshold(PN_stdfloat thresh0, PN_stdfloat val0, PN_stdfloat thresh1, PN_stdfloat val1) {
@@ -94,8 +107,11 @@ make_double_threshold(PN_stdfloat thresh0, PN_stdfloat val0, PN_stdfloat thresh1
  * However, the monitor has finite contrast.  Normally, all of that contrast
  * is used to represent brightnesses in the range 0-1.  The HDR0 tone mapping
  * operator 'steals' one quarter of that contrast to represent brightnesses in
- * the range 1-infinity.  @code FINAL_RGB = (RGB^3 + RGB^2 + RGB) / (RGB^3 +
- * RGB^2 + RGB + 1) @endcode
+ * the range 1-infinity.
+ *
+ * @code
+ * FINAL_RGB = (RGB^3 + RGB^2 + RGB) / (RGB^3 + RGB^2 + RGB + 1)
+ * @endcode
  */
 CPT(RenderAttrib) LightRampAttrib::
 make_hdr0() {
@@ -117,7 +133,10 @@ make_hdr0() {
  * However, the monitor has finite contrast.  Normally, all of that contrast
  * is used to represent brightnesses in the range 0-1.  The HDR1 tone mapping
  * operator 'steals' one third of that contrast to represent brightnesses in
- * the range 1-infinity.  @code FINAL_RGB = (RGB^2 + RGB) / (RGB^2 + RGB + 1)
+ * the range 1-infinity.
+ *
+ * @code
+ * FINAL_RGB = (RGB^2 + RGB) / (RGB^2 + RGB + 1)
  * @endcode
  */
 CPT(RenderAttrib) LightRampAttrib::
@@ -140,7 +159,11 @@ make_hdr1() {
  * However, the monitor has finite contrast.  Normally, all of that contrast
  * is used to represent brightnesses in the range 0-1.  The HDR2 tone mapping
  * operator 'steals' one half of that contrast to represent brightnesses in
- * the range 1-infinity.  @code FINAL_RGB = (RGB) / (RGB + 1) @endcode
+ * the range 1-infinity.
+ *
+ * @code
+ * FINAL_RGB = (RGB) / (RGB + 1)
+ * @endcode
  */
 CPT(RenderAttrib) LightRampAttrib::
 make_hdr2() {
diff --git a/panda/src/physics/linearUserDefinedForce.h b/panda/src/physics/linearUserDefinedForce.h
index 1edc850828..fea6612de8 100644
--- a/panda/src/physics/linearUserDefinedForce.h
+++ b/panda/src/physics/linearUserDefinedForce.h
@@ -17,12 +17,7 @@
 #include "linearForce.h"
 
 /**
- * a programmable force that takes an evaluator fn.
- *
- * NOTE : AS OF Interrogate => Squeak, this class does NOT get FFI'd due to
- * the function pointer bug, and is currently NOT getting interrogated.
- * Change this in the makefile when the time is right or this class becomes
- * needed...
+ * A programmable force that takes an evaluator function.
  */
 class EXPCL_PANDAPHYSICS LinearUserDefinedForce : public LinearForce {
 PUBLISHED: