Docstring Audit

As per ticket #5, the docstrings in PLWM need a thorough update. Eventually we'd like to generate most PLWM documentation directly from the source using pydoc.

Guidelines

Docstrings should:

• Be formatted to follow PEP 257. For example:

  class ModeWindowXMMS2:
      """WM mixin providing an XMMS2 status display in the ModeWindow.
  
      Example:
  
      >>> from plwm import mw_xmms2, wmanager, modewindow
      >>> class MyScreen(wmanager.Screen, modewindow.ModeWindowScreen):
      ...     pass
      ... 
      >>> class MyWM(wmanager.WindowManager, mw_xmms2.ModeWindowXMMS2):
      ...     screen_class = MyScreen
      ...     mw_xmms2_position = 0.7
      ...     mw_xmms2_justification = modewindow.RIGHT
      ... 
  
      """
      mw_xmms2_position = 0.3
      mw_xmms2_justification = modewindow.LEFT
  

  Not:

  class ModeWindowXMMS2:
      """
      WM mixin providing an XMMS2 status display in the ModeWindow.
  
      Example:
  
      >>> from plwm import mw_xmms2, wmanager, modewindow
      >>> class MyScreen(wmanager.Screen, modewindow.ModeWindowScreen):
      ...     pass
      ... 
      >>> class MyWM(wmanager.WindowManager, mw_xmms2.ModeWindowXMMS2):
      ...     screen_class = MyScreen
      ...     mw_xmms2_position = 0.7
      ...     mw_xmms2_justification = modewindow.RIGHT
      ..."""
      mw_xmms2_position = 0.3
      mw_xmms2_justification = modewindow.LEFT
  

• Include doctest-compatible code examples when possible. This provides more useful documentation and simplifies unit testing.
• Be included on every public module, class, function, and method.

Progress

In the following list, a crossed out file has already been finished, and an underlined file is in progress. If you have chosen a file to work on, please underline it and list your name next to it before starting your changes; this ensures that someone else doesn't duplicate your work.

• examples
  • examplewm.py - whitelynx - [217], [218]
  • hrwwm.py
  • petliwm.py
  • plpwm.py
  • senapwm.py
  • xmlcontrol.py
• plwm
  • __init__.py
  • border.py
  • cfilter.py
  • color.py
  • composite.py
  • cycle.py
  • deltamove.py
  • event.py
  • focus.py
  • font.py
  • frame.py
  • input.py
  • inspect.py
  • keys.py
  • menu.py
  • message.py
  • misc.py
  • mixer.py
  • modestatus.py
  • modewindow.py
  • mouse.py
  • moveresize.py
  • mw_acpi.py
  • mw_apm.py
  • mw_biff.py
  • mw_clock.py
  • mw_gmail.py
  • mw_load.py
  • mw_watchfiles.py
  • mw_xmms.py
  • mw_xmms2.py - whitelynx - [219]
  • opacity.py
  • outline.py
  • pane_utilities.py
  • panes.py
  • statusbar.py
  • views.py
  • wmanager.py
  • wmevents.py
• setup.py
• utils
  • inspect_plwm.py
  • wmm.py