Updates and corrections to the BPy doc. Patch #2975

A large chunk of documentation goodness from Campbell Barton (ideasman).
Thanks!

Note that any mispellings, errors, or inconsistencies are due to
my ham-fisted editing.

7 files changed, 122 insertions, 92 deletions

diff --git a/source/blender/python/api2_2x/doc/API_intro.py b/source/blender/python/api2_2x/doc/API_intro.py
index c2b4df3fbba..49d4aaac3f7 100644
--- a/source/blender/python/api2_2x/doc/API_intro.py
+++ b/source/blender/python/api2_2x/doc/API_intro.py
@@ -42,11 +42,12 @@ The Blender Python API Reference
   - L{Text3d}
      - L{Font}
   - L{Texture}
+  - L{TimeLine}
   - L{Types}
   - L{Window}
      - L{Theme}
   - L{World}
-  - L{sys<Sys>}
+  - L{sys}
 
  Additional information:
  -----------------------
@@ -87,7 +88,7 @@ These are the basic ways to execute scripts in Blender:
  'blender myfile.blend -P textname'.
  3. Via command line in I{background mode}: use the '-b' flag (the order is
  important): C{blender -b <blendfile> -P <scriptname>}.  <blendfile> can be any
- .blend file, including the default .B.blend that is in Blender's home dir
+ .blend file, including the default .B.blend that is in Blender's home directory
  L{Blender.Get}('homedir'). In this mode no window will be opened and the
  program will leave as soon as the script finishes execution.
  4. Properly registered scripts can be selected directly from the program's
@@ -108,7 +109,7 @@ Interaction with users:
  Scripts can:
   - simply run and exit;
   - pop messages, menus and small number and text input boxes;
-  - draw graphical user interfaces (guis) with OpenGL calls and native
+  - draw graphical user interfaces (GUIs) with OpenGL calls and native
     program buttons, which stay there accepting user input like any other
     Blender window until the user closes them;
   - attach themselves to a space's event or drawing code (aka space handlers,
@@ -121,7 +122,7 @@ Interaction with users:
   - use external Python libraries, if available.
 
  You can read the documentation for the L{Window}, L{Draw} and L{BGL} modules
- for more information and also check Python's site for external modules that
+ for more information and also check the Python site for external modules that
  might be useful to you.  Note though that any imported module will become a
  requirement of your script, since Blender itself does not bundle external
  modules.
@@ -129,7 +130,7 @@ Interaction with users:
 Command line mode:
 ------------------
 
- Python was embedded in Blender, so to access bpython modules you need to
+ Python was embedded in Blender, so to access BPython modules you need to
  run scripts from the program itself: you can't import the Blender module
  into an external Python interpreter.
 
@@ -175,9 +176,9 @@ Blender Data Structures:
 ------------------------
 
  Programs manipulate data structures.  Blender python scripts are no exception.
- Blender uses an Object Oriented architecture.  The bpython interface tries to
+ Blender uses an Object Oriented architecture.  The BPython interface tries to
  present Blender objects and their attributes in the same way you see them
- through the User Interface (the GUI).  One key to bpython programming is
+ through the User Interface (the GUI).  One key to BPython programming is
  understanding the information presented in Blender's OOPS window where Blender
  objects and their relationships are displayed.
 
@@ -207,7 +208,7 @@ A note to newbie script writers:
  many applications the difference is negligible or acceptable.  Also, with
  profiling (or even simple direct timing with L{Blender.sys.time<Sys.time>}) to
  identify slow areas and well thought optimizations, the speed can be
- I{considerably} improved in many cases.  Try some of the best bpython scripts
+ I{considerably} improved in many cases.  Try some of the best BPython scripts
  to get an idea of what can be done, you may be surprised.
 
 @author: The Blender Python Team
@@ -224,9 +225,9 @@ A note to newbie script writers:
    pdf.  For pdf it requires a working LaTeX environment.
 
 @note: the official version of this reference guide is only updated for each
-   new Blender release.  But it is simple to build yourself current cvs
-   versions of this text: install epydoc, grab all files in the
-   source/blender/python/api2_2x/doc/ folder of Blender's cvs and use the
+   new Blender release.  But you can build the current CVS
+   version yourself: install epydoc, grab all files in the
+   source/blender/python/api2_2x/doc/ folder of Blender's CVS and use the
    epy_docgen.sh script also found there to generate the html docs.
    Naturally you will also need a recent Blender binary to try the new
    features.  If you prefer not to compile it yourself, there is a testing
diff --git a/source/blender/python/api2_2x/doc/Draw.py b/source/blender/python/api2_2x/doc/Draw.py
index c97331c5cfe..b88eade5d00 100644
--- a/source/blender/python/api2_2x/doc/Draw.py
+++ b/source/blender/python/api2_2x/doc/Draw.py
@@ -7,7 +7,7 @@ Draw
 ====
 
 B{New}:
- - access to ascii values in L{events<Register>} callbacks;
+ - access to ASCII values in L{events<Register>} callbacks;
  - 'large' fonts for L{Text} and L{GetStringWidth}.
 
 This module provides access to a B{windowing interface} in Blender.  Its widgets
@@ -243,7 +243,7 @@ def Register(draw = None, event = None, button = None):
       they will stay until Draw.Exit is called.  It's enough to redraw the
       screen, when a relevant event is caught.
   @note: only during the B{event} callback: the L{Blender}.ascii variable holds
-      the ascii integer value (if it exists and is valid) of the current event.
+      the ASCII integer value (if it exists and is valid) of the current event.
   """
 
 def Redraw(after = 0):
@@ -632,6 +632,10 @@ def Image(image, x, y, zoomx=1.0, zoomy=1.0, clipx=0, clipy=0, clipw=-1, cliph=-
   either the width or the height of the clipping rectangle are negative then
   the corresponding dimension (width or height) is set to include as much of 
   the image as possible.
+  
+  For drawing images with alpha blending with the background you will need to enable blending as shown in the example.
+  
+  
 
   Example::
    import Blender
@@ -640,7 +644,12 @@ def Image(image, x, y, zoomx=1.0, zoomy=1.0, clipx=0, clipy=0, clipw=-1, cliph=-
    myimage = Image.Load('myimage.png')
 
    def gui():
+        BGL.glEnable( BGL.GL_BLEND ) # Only needed for alpha blending images with background.
+        BGL.glBlendFunc(BGL.GL_SRC_ALPHA, BGL.GL_ONE_MINUS_SRC_ALPHA) 
+        
         Draw.Image(myimage, 50, 50)
+        
+        BGL.glDisable( BGL.GL_BLEND )
    def event(evt, val):
         if evt == Draw.ESCKEY:
               Draw.Exit()
diff --git a/source/blender/python/api2_2x/doc/NMesh.py b/source/blender/python/api2_2x/doc/NMesh.py
index 9d253f15c17..301c9398188 100644
--- a/source/blender/python/api2_2x/doc/NMesh.py
+++ b/source/blender/python/api2_2x/doc/NMesh.py
@@ -4,11 +4,11 @@
 The Blender.NMesh submodule.
 
 B{New}:
- - edges class (L{NMEdge}) and nmesh methods (L{NMesh.addEdge},
-L{NMesh.addEdgesData}, etc.);
- - new optional arguments to L{NMesh.update};
- - L{NMesh.transform};
- - L{GetNames}.
+ - edges class (L{NMEdge}) and nmesh methods (L{NMesh.NMesh.addEdge},
+L{NMesh.NMesh.addEdgesData}, etc.);
+ - new optional arguments to L{NMesh.NMesh.update};
+ - L{NMesh.NMesh.transform};
+ - L{GetNames};
  - L{GetRawFromObject} supports Surface/Curve/Text/Meta objects
 
 Mesh Data
@@ -74,7 +74,7 @@ Example::
     - TILES - uses tiled image.
     - TWOSIDE - two-sided face.
 @var FaceTranspModes: The available face transparency modes. Note: these are
-  ENUMS, they can't be combined (and'ed, or'ed, etc) like a bit vector.
+  enumerated values (enums), they can't be combined (and'ed, or'ed, etc) like a bit vector.
     - SOLID - draw solid.
     - ADD - add to background (halo).
     - ALPHA - draw with transparency.
@@ -161,7 +161,7 @@ def GetRawFromObject(name):
       matters, the rendering one is only processed at the rendering pre-stage
       and is not available for scripts.  This is not a problem at all, since
       you can get and set the subdivision levels via scripting, too (see
-      L{NMesh.getSubDivLevels}, L{NMesh.setSubDivLevels}).
+      L{NMesh.NMesh.getSubDivLevels}, L{NMesh.NMesh.setSubDivLevels}).
   @note: Meshes extracted from curve based objects (Font/2D filled curves)
       contain both the filled surfaces and the outlines of the shapes.
   @warn: This function gets I{deformed} mesh data, already modified for
@@ -296,12 +296,12 @@ class NMFace:
   @type sel: bool
   @ivar sel: The selection state (1: selected, 0: unselected) of this NMesh's
       faces *in edit mode*.  This is not the same as the selection state of
-      the textured faces (see L{NMesh.NMFace.flag}).
+      the textured faces (see L{flag}).
   @type hide: bool
   @ivar hide: The visibility state (1: hidden, 0: visible) of this NMesh's
       faces *in edit mode*.  This is not the same as the visibility state of
-      the textured faces (see L{NMesh.NMFace.flag}).
-  @ivar col: The list of vertex colours.
+      the textured faces (see L{flag}).
+  @ivar col: The list of vertex colors.
   @ivar mat: Same as I{materialIndex} below.
   @ivar materialIndex: The index of this face's material in its NMesh materials
       list.
@@ -319,8 +319,8 @@ class NMFace:
   @note: there are normal faces and textured faces in Blender, both currently
     with their own selection and visibility states, due to a mix of old and new
     code.  To (un)select or (un)hide normal faces (visible in editmode), use
-    L{NMFace.sel} and L{NMFace.hide} vars.  For textured faces (Face Select
-    mode in Blender) use the old L{NMFace.flag} bitflag.  Also check the
+    L{sel} and L{hide} variables.  For textured faces (Face Select
+    mode in Blender) use the old L{flag} bitflag.  Also check the
     example above and note L{Window.EditMode}.
   @note: Assigning uv textures to mesh faces in Blender works like this:
     1. Select your mesh.
@@ -329,7 +329,7 @@ class NMFace:
     4. Play in both windows (better split the screen to see both at the same
        time) until the uv coordinates are where you want them.  Hint: in the
        3d window, the 'u' key opens a menu of default uv choices and the 'r'
-       key lets you rotate the uv coords.
+       key lets you rotate the uv coordinates.
     5. Leave face select mode (press f).
   """
 
@@ -349,7 +349,7 @@ class NMesh:
   @ivar name: The NMesh name.  It's common to use this field to store extra
      data about the mesh (to be exported to another program, for example).
   @ivar materials: The list of materials used by this NMesh.  See
-     L{NMesh.getMaterials} for important details.
+     L{getMaterials} for important details.
   @ivar verts: The list of NMesh vertices (NMVerts).
   @ivar users: The number of Objects using (linked to) this mesh.
   @ivar faces: The list of NMesh faces (NMFaces).
@@ -438,7 +438,7 @@ class NMesh:
         - -1: return the current nmesh's list;
         -  0: retrieve a fresh list from the Blender mesh -- eventual
               modifications made by the script not included, unless
-              L{NMesh.update} is called before this method;
+              L{update} is called before this method;
         -  1: like 0, but empty slots are not ignored, they are returned as
               None's.
     @note: what >= 0 also updates nmesh.materials attribute.
@@ -461,22 +461,22 @@ class NMesh:
 
   def hasVertexColours(flag = None):
     """
-    Get (and optionally set) if this NMesh has vertex colours.
+    Get (and optionally set) if this NMesh has vertex colors.
     @type flag: int
-    @param flag: If given and non-zero, the "vertex colour" flag for this NMesh
+    @param flag: If given and non-zero, the "vertex color" flag for this NMesh
         is turned I{on}.
     @rtype: bool
-    @return: The current value of the "vertex colour" flag.
-    @warn: If a mesh has both vertex colours and textured faces, this function
+    @return: The current value of the "vertex color" flag.
+    @warn: If a mesh has both vertex colors and textured faces, this function
        will return False.  This is due to the way Blender deals internally with
-       the vertex colours array (if there are textured faces, it is copied to
+       the vertex colors array (if there are textured faces, it is copied to
        the textured face structure and the original array is freed/deleted).
        If you want to know if a mesh has both textured faces and vertex
-       colours, set *in Blender* the "VCol Paint" flag for each material that
+       colors, set *in Blender* the "VCol Paint" flag for each material that
        covers an area that was also vertex painted and then check in your
        Python script if that material flag is set.  Of course also tell others
        who use your script to do the same.  The "VCol Paint" material mode flag
-       is the way to tell Blender itself to render with vertex colours, too, so
+       is the way to tell Blender itself to render with vertex colors, too, so
        it's a natural solution.
     """
 
diff --git a/source/blender/python/api2_2x/doc/Object.py b/source/blender/python/api2_2x/doc/Object.py
index 54a6114c509..52b7defa88e 100644
--- a/source/blender/python/api2_2x/doc/Object.py
+++ b/source/blender/python/api2_2x/doc/Object.py
@@ -105,6 +105,7 @@ class Object:
   The Object object
   =================
     This object gives access to generic data from all objects in Blender.
+    
     @ivar LocX: The X location coordinate of the object.
     @ivar LocY: The Y location coordinate of the object.
     @ivar LocZ: The Z location coordinate of the object.
@@ -140,7 +141,7 @@ class Object:
     @ivar dsize: The delta (X,Y,Z) size of the object.
     @type Layers: integer (bitmask)
     @ivar Layers: The object layers (also check the newer attribute
-        L{layers<Object.Object.layers>}).  This value is a bitmask with at 
+        L{layers<layers>}).  This value is a bitmask with at 
         least one position set for the 20 possible layers starting from the low
         order bit.  The easiest way to deal with these values in in hexadecimal
         notation.
@@ -150,7 +151,7 @@ class Object:
         the interface.
     @type layers: list of integers
     @ivar layers: The layers this object is visible in (also check the older
-        attribute L{Layers<Object.Object.Layers>}).  This returns a list of
+        attribute L{Layers<Layers>}).  This returns a list of
         integers in the range [1, 20], each number representing the respective
         layer.  Setting is done by passing a list of ints or an empty list for
         no layers.
@@ -180,7 +181,7 @@ class Object:
         of: 2 - axis, 4 - texspace, 8 - drawname, 16 - drawimage,
         32 - drawwire.
     @ivar name: The name of the object.
-    @ivar sel: The selection state of the object, 1/0.  
+    @ivar sel: The selection state of the object in the current scene, 1 is selected, 0 is unselected.  
   """
 
   def buildParts():
@@ -257,9 +258,9 @@ class Object:
 
   def getEuler():
     """
-    Returns the object's rotation as Euler rotation vector (rotX, rotY, rotZ).  Angles are in radians.
+    Returns the object's localspace rotation as Euler rotation vector (rotX, rotY, rotZ).  Angles are in radians.
     @rtype: Py_Euler
-    @return: A python euler 
+    @return: A python Euler 
     """
 
   def getInverseMatrix():
@@ -277,7 +278,7 @@ class Object:
     """
   def isSelected():
     """
-    Returns the objects selection state as a boolean value True or False.
+    Returns the objects selection state in the current scene as a boolean value True or False.
     @rtype: Boolean
     @return: Selection state as True or False
     """
@@ -323,7 +324,7 @@ class Object:
     @type space: string
     @param space: The desired matrix:
       - worldspace (default): absolute, taking vertex parents, tracking and
-          ipo's into account;
+          Ipo's into account;
       - localspace: relative to the object's parent;
       - old_worldspace: old behavior, prior to Blender 2.34, where eventual
           changes made by the script itself were not taken into account until
@@ -396,9 +397,9 @@ class Object:
 
     The example below works on the default scene. It retrieves all objects in
     the scene and updates the location and rotation of the camera. When run,
-    the camera will rotate 180 degrees and moved to the oposite side of the X
+    the camera will rotate 180 degrees and moved to the opposite side of the X
     axis. Note that the number 'pi' in the example is an approximation of the
-    true number 'pi'::
+    true number 'pi'.  A better, less error-prone value of pi is math.pi from the python math module.::
         import Blender
 
         objects = Blender.Object.Get()
@@ -413,7 +414,7 @@ class Object:
 
   def getDupliVerts():
     """
-    Get state of DupliVerts anim propertie
+    Get state of DupliVerts animation property
     @return: a boolean value.
     """
 
@@ -435,12 +436,12 @@ class Object:
     @return: py_none
     """
 
-  def link(object):
+  def link(datablock):
     """
-    Links Object with data provided in the argument. The data must match the
+    Links Object with ObData datablock provided in the argument. The data must match the
     Object's type, so you cannot link a Lamp to a Mesh type object.
-    @type object: Blender Object
-    @param object: A Blender Object.
+    @type datablock: Blender ObData datablock
+    @param datablock: A Blender datablock matching the objects type.
     """
 
   def makeParent(objects, noninverse = 0, fast = 0):
@@ -448,7 +449,7 @@ class Object:
     Makes the object the parent of the objects provided in the argument which
     must be a list of valid Objects.
     @type objects: Sequence of Blender Object
-    @param objects: The Childs of the parent
+    @param objects: The children of the parent
     @type noninverse: Integer
     @param noninverse:
         0 - make parent with inverse
@@ -469,7 +470,7 @@ class Object:
     which must be a list of valid Objects.
     The parent object must be a Curve or Armature.
     @type objects: Sequence of Blender Object
-    @param objects: The Childs of the parent
+    @param objects: The children of the parent
     @type noninverse: Integer
     @param noninverse:
         0 - make parent with inverse
@@ -492,9 +493,9 @@ class Object:
     which must be a list of valid Objects.
     The parent object must be a Mesh, Curve or Surface.
     @type objects: Sequence of Blender Object
-    @param objects: The Childs of the parent
+    @param objects: The children of the parent
     @type indices: Tuple of Integers
-    @param indices: The indices of the vertice you want to parent to (1 or 3)
+    @param indices: The indices of the vertices you want to parent to (1 or 3 values)
     @type noninverse: Integer
     @param noninverse:
         0 - make parent with inverse
@@ -544,9 +545,9 @@ class Object:
 
   def setEuler(euler):
     """
-    Sets the object's rotation according to the specified Euler angles.
+    Sets the object's localspace rotation according to the specified Euler angles.
     @type euler: Py_Euler or a list of floats
-    @param euler: a python euler or x,y,z rotations as floats
+    @param euler: a python Euler or x,y,z rotations as floats
     """
 
   def setIpo(ipo):
@@ -558,7 +559,7 @@ class Object:
 
   def setLocation(x, y, z):
     """
-    Sets the object's location.
+    Sets the object's location relative to the parent object (if any).
     @type x: float
     @param x: The X coordinate of the new location.
     @type y: float
@@ -569,28 +570,28 @@ class Object:
 
   def setMaterials(materials):
     """
-    Sets the materials. The argument must be a list of valid material objects.
+    Sets the materials. The argument must be a list 16 items or less.  Each list element is either a Material or None.
     @type materials: Materials list
     @param materials: A list of Blender material objects.
     """
 
   def setMatrix(matrix):
     """
-    Sets the object's matrix and updates it's tranformation. 
+    Sets the object's matrix and updates it's transformation. 
     @type matrix: Py_Matrix 4x4
     @param matrix: a python matrix 4x4.
     """
 
   def setName(name):
     """
-    Sets the name of the object.
+    Sets the name of the object. A string longer then 20 characters will be shortened.
     @type name: String
     @param name: The new name for the object.
     """
 
   def setSize(x, y, z):
     """
-    Sets the object's size.
+    Sets the object's size, relative to the parent object (if any)
     @type x: float
     @param x: The X size multiplier.
     @type y: float
@@ -616,7 +617,7 @@ class Object:
   
   def select(boolean):
     """
-    Sets the object's selection state.
+    Sets the object's selection state in the current scene.
     @type boolean: Integer
     @param boolean:
         - 0  - unselected
@@ -625,7 +626,7 @@ class Object:
   
   def getBoundBox():
     """
-    Returns the bounding box of this object.  This works for meshes (out of
+    Returns the worldspace bounding box of this object.  This works for meshes (out of
     edit mode) and curves.
     @rtype: list of 8 (x,y,z) float coordinate vectors
     @return: The coordinates of the 8 corners of the bounding box.
@@ -777,12 +778,12 @@ class Object:
     """
     Copies all properties from one object to another.
     @type object: Object object
-    @param object: Object that will recieve the properties.
+    @param object: Object that will receive the properties.
     """
 
   def setDupliVerts(data):
     """
-    Set state of DupliVerts anim propertie
+    Set state of DupliVerts animation property
     @param data: boolean value True, False, 0 or not 0.
     """
 
@@ -934,17 +935,17 @@ class Property:
 
   def getPIPermf():
     """
-    Get the Object's Particle Interaction Permiability.
+    Get the Object's Particle Interaction Permeability.
     @rtype: float
     """
 
   def setPIPerm(perm):
     """
-    Set the the Object's Particle Interaction Permiability.
+    Set the the Object's Particle Interaction Permeability.
     Values between 0 to 10.0
     @rtype: PyNone
     @type perm: float
-    @param perm: the Object's Particle Interaction New Permiability.
+    @param perm: the Object's Particle Interaction New Permeability.
     """    
 
   def getPIRandomDamp():
@@ -1151,7 +1152,7 @@ class Property:
 
   def setSBEnable(switch):
     """
-    Enable / Disable Softbodies.
+    Enable / Disable SoftBodies.
     1: on
     0: off
     @rtype: PyNone
@@ -1161,13 +1162,13 @@ class Property:
 
   def getSBPostDef():
     """
-    get Softbodies PostDef option
+    get SoftBodies PostDef option
     @rtype: int
     """
 
   def setSBPostDef(switch):
     """
-    Enable / Disable Softbodies PostDef option
+    Enable / Disable SoftBodies PostDef option
     1: on
     0: off
     @rtype: PyNone
@@ -1177,13 +1178,13 @@ class Property:
 
   def getSBUseGoal():
     """
-    get Softbodies UseGoal option
+    get SoftBodies UseGoal option
     @rtype: int
     """
 
   def setSBUseGoal(switch):
     """
-    Enable / Disable Softbodies UseGoal option
+    Enable / Disable SoftBodies UseGoal option
     1: on
     0: off
     @rtype: PyNone
@@ -1192,13 +1193,13 @@ class Property:
     """ 
   def getSBUseEdges():
     """
-    get Softbodies UseEdges option
+    get SoftBodies UseEdges option
     @rtype: int
     """
 
   def setSBUseEdges(switch):
     """
-    Enable / Disable Softbodies UseEdges option
+    Enable / Disable SoftBodies UseEdges option
     1: on
     0: off
     @rtype: PyNone
@@ -1208,13 +1209,13 @@ class Property:
     
   def getSBStiffQuads():
     """
-    get Softbodies StiffQuads option
+    get SoftBodies StiffQuads option
     @rtype: int
     """
 
   def setSBStiffQuads(switch):
     """
-    Enable / Disable Softbodies StiffQuads option
+    Enable / Disable SoftBodies StiffQuads option
     1: on
     0: off
     @rtype: PyNone
diff --git a/source/blender/python/api2_2x/doc/Scene.py b/source/blender/python/api2_2x/doc/Scene.py
index d871cc714ba..3028b1cab6c 100644
--- a/source/blender/python/api2_2x/doc/Scene.py
+++ b/source/blender/python/api2_2x/doc/Scene.py
@@ -4,10 +4,10 @@
 The Blender.Scene submodule.
 
 B{New}:
-  - L{Scene.clearScriptLinks} accepts a parameter now.
-  - L{Scene.getLayers}, L{Scene.setLayers} and the L{layers<Scene.layers>} and
-    L{Layers<Scene.Layers>} Scene attributes. 
-  - L{Scene.getActiveObject} method.
+  - L{Scene.clearScriptLinks<Scene.Scene.clearScriptLinks>} accepts a parameter now.
+  - acess methods L{Scene.getLayers<Scene.Scene.getLayers>}, L{Scene.setLayers<Scene.Scene.setLayers>} via lists to complement the layers and
+    Layers Scene attributes which use bitmasks. 
+  - L{Scene.getActiveObject<Scene.Scene.getActiveObject>} method.
 
 Scene
 =====
@@ -30,11 +30,11 @@ Example::
 @warn: as done in the example (*), it's recommended to first link object data to
     objects and only after that link objects to scene.  This is because if
     there is no object data linked to an object ob, scene.link(ob) will
-    automatically create the missing data.  This is ok on its own, but I{if
+    automatically create the missing data.  This is OK on its own, but I{if
     after that} this object is linked to obdata, the automatically created one
     will be discarded -- as expected -- but will stay in Blender's memory
     space until the program is exited, since Blender doesn't really get rid of
-    most kinds of data.  So first linking obdata to object, then object to
+    most kinds of data.  So first linking ObData to object, then object to
     scene is a tiny tiny bit faster than the other way around and also saves
     some realtime memory (if many objects are created from scripts, the
     savings become important).
@@ -83,7 +83,7 @@ class Scene:
   @ivar name: The Scene name.
   @type Layers: integer (bitmask)
   @ivar Layers: The Scene layers (check also the easier to use
-        L{layers<Scene.Scene.layers>}).  This value is a bitmask with at least
+        L{layers}).  This value is a bitmask with at least
         one position set for the 20 possible layers starting from the low order
         bit.  The easiest way to deal with these values in in hexadecimal 
         notation.
@@ -94,7 +94,7 @@ class Scene:
         After setting the Layers value, the interface (at least the 3d View and
         the Buttons window) needs to be redrawn to show the changes.
   @type layers: list of integers
-  @ivar layers: The Scene layers (check also L{Layers<Scene.Scene.Layers>}).
+  @ivar layers: The Scene layers (check also L{Layers}).
         This attribute accepts and returns a list of integer values in the
         range [1, 20].
         Example::
@@ -207,8 +207,9 @@ class Scene:
   def getCurrentCamera():
     """
     Get the currently active Camera for this Scene.
-    @rtype: Blender Camera
-    @return: The currently active Camera.
+    @note: The active camera can be any object type, not just a camera object.
+    @rtype: Blender Object
+    @return: The currently active Camera object.
     """
 
   def setCurrentCamera(camera):
@@ -253,6 +254,24 @@ class Scene:
   def addScriptLink (text, event):
     """
     Add a new script link to this Scene.
+    
+    Using OpenGL functions within a scene ScriptLink will draw graphics over the 3D view.
+    There is an issue with the zoom of the floating panels also scaling graphics drawn by your scriptlink.
+    This makes matching OpenGL graphics to mouse location impossible.
+    Make sure that you use floating point for operations that you would usually use int functions for: glRasterPos2f rather then glRasterPos2i.
+    
+    The following example shows how you can use the OpenGL model view matrix to obtain the scale value.
+    
+    Example::
+      from Blender import BGL
+      view_matrix = BGL.Buffer(BGL.GL_FLOAT, 16)
+      BGL.glGetFloatv(BGL.GL_MODELVIEW_MATRIX, view_matrix)
+      gl_scale = 1/viewMatrix[0]
+      
+      # Now that we have the scale we can draw to the correct scale.
+      BGL.glRect2f(10*gl_scale, 10*gl_scale, 110*gl_scale, 110*gl_scale)
+      
+      
     @type text: string
     @param text: the name of an existing Blender L{Text}.
     @type event: string
diff --git a/source/blender/python/api2_2x/doc/Theme.py b/source/blender/python/api2_2x/doc/Theme.py
index bd7371106ad..743b40a7e8b 100644
--- a/source/blender/python/api2_2x/doc/Theme.py
+++ b/source/blender/python/api2_2x/doc/Theme.py
@@ -17,7 +17,7 @@ Example::
   theme = Theme.Get()[0] # get current theme
 
   def write_theme(filename):
-    "Write the current theme as a bpython script"
+    "Write the current theme as a BPython script"
 
     f = file(filename, "w")
 
@@ -96,7 +96,7 @@ class Theme:
     Get a space or the ui (sub)theme from this Theme.
     @type t: string, int or None
     @param t: the wanted sub-theme as either:
-        - int: -1 for UI or the types in L{Window.Types} for the others;
+        - int: -1 for UI or the types in L{Window.Types<Window.Types>} for the others;
         - string: use get() to know them (they are case insensitive);
         - nothing: as written above, get() returns a list of names.
     @rtype: Blender ThemeSpace or ThemeUI or list of sub-theme types as strings.
diff --git a/source/blender/python/api2_2x/doc/Window.py b/source/blender/python/api2_2x/doc/Window.py
index caaf22710d8..b60dbaf0aed 100644
--- a/source/blender/python/api2_2x/doc/Window.py
+++ b/source/blender/python/api2_2x/doc/Window.py
@@ -403,14 +403,14 @@ def GetMouseButtons ():
   """
   Get the current mouse button state (see / compare against L{MButs}).
   @rtype: int
-  @return: an or'ed flag with the currently pressed buttons.
+  @return: an OR'ed flag with the currently pressed buttons.
   """
 
 def GetKeyQualifiers ():
   """
   Get the current qualifier keys state (see / compare against L{Qual}).
   @rtype: int
-  @return: an or'ed combination of values in L{Window.Qual}.
+  @return: an OR'ed combination of values in L{Qual}.
   """
 
 def SetKeyQualifiers (qual):
@@ -418,7 +418,7 @@ def SetKeyQualifiers (qual):
   Fake qualifier keys state.  This is useful because some key events require
   one or more qualifiers to be active (see L{QAdd}).
   @type qual: int
-  @param qual: an or'ed combination of values in L{Window.Qual}.
+  @param qual: an OR'ed combination of values in L{Qual}.
   @rtype: int
   @return: the current state, that should be equal to 'qual'.
   @warn: remember to reset the qual keys to 0 once they are not necessary
@@ -465,7 +465,7 @@ def GetScreenInfo (type = -1, rect = 'win', screen = ''):
   """
   Get info about the current screen setup.
   @type type: int
-  @param type: the space type (see L{Window.Types}) to restrict the
+  @param type: the space type (see L{Types}) to restrict the
      results to.  If -1 (the default), info is reported about all available
      areas.
   @type rect: string