BPython -- a few fixes:

-- fixed bug #1689:
http://projects.blender.org/tracker/?func=detail&atid=125&aid=1689&group_id=9

Reported by Tom Musgrove (thanks), the problem was that Window.QHandle was not passing events to windows that had id's below the current active window.  It was a stupid mistake (mine), the code was iterating from curarea instead of from the first area in the areabase list.

-- fixed bug #1568:
http://projects.blender.org/tracker/index.php?func=detail&aid=1568&group_id=9&atid=125

Stephen investigated the problem, reported by Gabriel Beloin, and left hints in the bug report, thanks :).  I also implemented what he suggested, now Effect.Get('objname') returns a list with all objname's effects and as before, Get('objname, position') returns the effect at position 'position'.  Ref doc already updated.

-- Allowed menu registration lines to appear commented out -- Python comments: '#', of course -- (suggested by Michael Reimpell) in scripts:
Some Python doc tools need the doc strings between triple double-quotes, so to avoid conflicts scripts writers can now comment out the registration code, it should work anyway.  Michael also provided a patch for this a few days ago, too (thanks), but to keep changes at a minimum because of proximity to a release I didn't use it.

source/blender/python/api2_2x/doc/API_intro.py

@@ -18,7 +18,7 @@ The Blender Python API Reference
   - L{Camera}
   - L{Curve}
   - L{Draw}
-  - L{Effect}
+  - L{Effect} (*)
   - L{Image}
   - L{Ipo}
   - L{Lamp}
@@ -97,15 +97,16 @@ Registering scripts:
  The header should be like this one (all double and single apostrophes below
  are required)::
   #!BPY
-  \"\"\"
-  Name: 'Script Name'
-  Blender: 233
-  Group: 'Export'
-  Submenu: 'All' all
-  Submenu: 'Selected' sel
-  Submenu: 'Configure (gui)' gui
-  Tooltip: 'Export to some format.'
-  \"\"\"
+
+  # \"\"\"
+  # Name: 'Script Name'
+  # Blender: 233
+  # Group: 'Export'
+  # Submenu: 'All' all
+  # Submenu: 'Selected' sel
+  # Submenu: 'Configure (gui)' gui
+  # Tooltip: 'Export to some format.'
+  # \"\"\"
 
  where:
   - B{Name} is the string that will appear in the menu;
@@ -115,6 +116,15 @@ Registering scripts:
   - B{Submenu} adds optional submenus for further control;
   - B{Tooltip} is the (short) tooltip string for the menu entry.
 
+ note:
+  - all double and single apostrophes above are required;
+  - B{*NEW*}: you can "comment out" the header above, by starting lines with
+    '#', like we did.  This is not required (except for the first line, #!BPY,
+    of course), but this way the header won't conflict with Python tools that
+    you can use to generate documentation for your script code.  Just
+    remember to keep this header above any other line with triple
+    double-quotes (\"\"\") in your script.
+
  Submenu lines are not required, use them if you want to provide extra
  options.  To see which submenu the user chose, check the "__script__"
  dictionary in your code: __script__['arg'] has the defined keyword (the word