Added some details to the Object documentation, some parts were a big vague..

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

@@ -37,11 +37,12 @@ def New (type, name='type'):
   """
   Creates a new Object.
   @type type: string
-  @param type: The Object type: 'Armature', 'Camera', 'Curve', 'Lamp', 'Mesh'
+  @param type: The Object type: 'Armature', 'Camera', 'Curve', 'Lamp', 'Lattice',
-      or 'Empty'.
+      'Mball', 'Mesh', 'Surf' or 'Empty'.
   @type name: string
   @param name: The name of the object. By default, the name will be the same
       as the object type.
+      If the name is alredy in use, this new object will have a number at the end of the name.
   @return: The created Object.
 
   I{B{Example:}}
@@ -50,11 +51,11 @@ def New (type, name='type'):
   location (0, 0, 0) in the current scene::
     import Blender
 
-    object = Blender.Object.New ('Lamp')
+    object = Blender.Object.New('Lamp')
-    lamp = Blender.Lamp.New ('Spot')
+    lamp = Blender.Lamp.New('Spot')
-    object.link (lamp)
+    object.link(lamp)
-    scene = Blender.Scene.getCurrent ()
+    scene = Blender.Scene.GetCurrent()
-    scene.link (object)
+    scene.link(object)
 
     Blender.Redraw()
   """
@@ -70,8 +71,7 @@ def Get (name = None):
 
   I{B{Example 1:}}
 
-  The example below works on the default scene. The script returns the plane
+  The example below works on the default scene. The script returns the plane object and prints the location of the plane::
-  object and prints the location of the plane::
     import Blender
 
     object = Blender.Object.Get ('plane')
@@ -85,12 +85,15 @@ def Get (name = None):
 
     objects = Blender.Object.Get ()
     print objects
+  @note: Get will return objects from all scenes.
+      Most user tools should only operate on objects from the current scene - Blender.Scene.GetCurrent().getChildren()
   """
 
 def GetSelected ():
   """
-  Get the selected objects from Blender. If no objects are selected, an empty
+  Get the selected objects on visible layers from Blenders current scene. If no objects are selected, an empty
   list will be returned.
+  The active object of the current scene will always be the first object in the list (if selected).
   @return: A list of all selected Objects in the current scene.
 
   I{B{Example:}}
@@ -99,7 +102,7 @@ def GetSelected ():
   the script will print the selected objects::
     import Blender
 
-    objects = Blender.Object.GetSelected ()
+    objects = Blender.Object.GetSelected()
     print objects
   """
 
@@ -187,22 +190,22 @@ 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 in the current scene, 1 is selected, 0 is unselected.  
+    @ivar sel: The selection state of the object in the current scene, 1 is selected, 0 is unselected. (Selecting makes the object active)
     @ivar effects: The list of particle effects associated with the object.  (Read-only)
     @ivar parentbonename: The string name of the parent bone.
     @ivar users: The number of users of the object.  Read-only.
     @type users: int
     @ivar protectFlags: The "transform locking" bitfield flags for the object.  
     Setting bits lock the following attributes:
-	   - bit 0: X location
+       - bit 0: X location
-	   - bit 1: Y location
+       - bit 1: Y location
-	   - bit 2: Z location
+       - bit 2: Z location
-	   - bit 3: X rotation
+       - bit 3: X rotation
-	   - bit 4: Y rotation
+       - bit 4: Y rotation
-	   - bit 5: Z rotation
+       - bit 5: Z rotation
-	   - bit 6: X size
+       - bit 6: X size
-	   - bit 7: Y size
+       - bit 7: Y size
-	   - bit 8: Z size
+       - bit 8: Z size
     @type protectFlags: int
   """
 
@@ -399,7 +402,7 @@ class Object:
     For objects parented to bones, this is the name of the bone.
     @rtype: String
     @return: The parent object sub-name of the object.
-		If not available, None will be returned.
+      If not available, None will be returned.
     """
 
   def getTimeOffset():
@@ -418,7 +421,8 @@ class Object:
 
   def getType():
     """
-    Returns the type of the object.
+    Returns the type of the object in 'Armature', 'Camera', 'Curve', 'Lamp', 'Lattice',
+    'Mball', 'Mesh', 'Surf', 'Empty', 'Wave' (deprecated) or 'unknown' in exceptional cases.
     @return: The type of object.
 
     I{B{Example:}}
@@ -620,7 +624,7 @@ class Object:
 
   def setSize(x, y, z):
     """
-    Sets the object's size, relative to the parent object (if any)
+    Sets the object's size, relative to the parent object (if any), clamped 
     @type x: float
     @param x: The X size multiplier.
     @type y: float
@@ -647,6 +651,7 @@ class Object:
   def select(boolean):
     """
     Sets the object's selection state in the current scene.
+    setting the selection will make this object the active object of this scene.
     @type boolean: Integer
     @param boolean:
         - 0  - unselected