BGE Doc updates thanks to Roelf de Kock

--- Notes from Roelf, maybe some other BGE devs could help resolve these
Here is what I have so far. I've left "TODO's" were there needs to be some more comments.

The following things also need to be resolved:

-KX_VehicleWrapper.getWheelOrientationQuaternion looks like it should return a quaternion but if I look at the code it looks like it returns a rotation matrix.

-I still need to find out what exactly KX_VehicleWrapper.getWheelRotation is. I've got the return type but I would like to add some explanation for what it actualy means (and units if any).

-BL_Shader.setNumberOfPasses ignores the parameter but from the comment in the code it looks like the parameter that is being set (it is harcoded to be =1) in setNumberOfPasses is not used. So I'm not sure if this method should be documented at all.

4 files changed, 283 insertions, 263 deletions

diff --git a/source/gameengine/PyDoc/BL_Shader.py b/source/gameengine/PyDoc/BL_Shader.py
index 10e8b7c94ef..8fd4ae7c7ac 100644
--- a/source/gameengine/PyDoc/BL_Shader.py
+++ b/source/gameengine/PyDoc/BL_Shader.py
@@ -5,227 +5,244 @@ class BL_Shader(PyObjectPlus):
 	"""
 	BL_Shader GLSL shaders.
 	
-	All placeholders have a __ prefix
+	TODO - Description
 	"""
 	
-	def __setUniformfv(val):
+	def setUniformfv(name, fList):
 		"""
-		TODO - Description
+		Set a uniform with a list of float values
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param name: the uniform name
+		@type name: string
 		
-		@rtype: integer
-		@return: TODO Description
+		@param fList: a list (2, 3 or 4 elements) of float values
+		@type fList: list[float]
 		"""
 
-	def __delSource(val):
+	def delSource():
 		"""
 		TODO - Description
-		
-		@param val: the starting frame of the animation
-		@type val: float
-		
-		@rtype: integer
-		@return: TODO Description
+
 		"""
-	def __getFragmentProg(val):
+	def getFragmentProg():
 		"""
-		TODO - Description
-		
-		@param val: the starting frame of the animation
-		@type val: float
+		Returns the fragment program.
 		
-		@rtype: integer
-		@return: TODO Description
+		@rtype: string
+		@return: The fragment program.
 		"""
-	def __getVertexProg(val):
+	def getVertexProg():
 		"""
-		TODO - Description
+		Get the vertex program.
 		
-		@param val: the starting frame of the animation
-		@type val: float
-		
-		@rtype: integer
-		@return: TODO Description
+		@rtype: string
+		@return: The vertex program.
 		"""
-	def __isValid(val):
+	def isValid():
 		"""
-		TODO - Description
-		
-		@param val: the starting frame of the animation
-		@type val: float
-		
-		@rtype: integer
-		@return: TODO Description
+		Check if the shader is valid.
+
+		@rtype: bool
+		@return: True if the shader is valid
 		"""
-	def __setAttrib(val):
+	def setAttrib(enum):
 		"""
-		TODO - Description
-		
-		@param val: the starting frame of the animation
-		@type val: float
+		Set attribute location. (The parameter is ignored a.t.m. and the value of "tangent" is always used.)
 		
-		@rtype: integer
-		@return: TODO Description
+		@param enum: attribute location value
+		@type enum: integer
 		"""
-	def __setNumberOfPasses(val):
+	def setNumberOfPasses( max_pass ):
 		"""
-		TODO - Description
-		
-		@param val: the starting frame of the animation
-		@type val: float
+		Set the maximum number of passes. Not used a.t.m.
 		
-		@rtype: integer
-		@return: TODO Description
+		@param max_pass: the maximum number of passes
+		@type max_pass: integer
 		"""
-	def __setSampler(val):
+	def setSampler(name, index):
 		"""
-		TODO - Description
-		
-		@param val: the starting frame of the animation
-		@type val: float
+		Set uniform texture sample index.
 		
-		@rtype: integer
-		@return: TODO Description
+		@param name: Uniform name
+		@type name: string
+
+		@param index: Texture sample index.
+		@type index: integer
 		"""
-	def __setSource(val):
+	def setSource(vertexProgram, fragmentProgram):
 		"""
-		TODO - Description
-		
-		@param val: the starting frame of the animation
-		@type val: float
+		Set the vertex and fragment programs
 		
-		@rtype: integer
-		@return: TODO Description
+		@param vertexProgram: Vertex program
+		@type vertexProgram: string
+
+		@param fragmentProgram: Fragment program
+		@type fragmentProgram: string
 		"""
-	def __setUniform1f(val):
+	def setUniform1f(name, fx):
 		"""
-		TODO - Description
+		Set a uniform with 1 float value.
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param name: the uniform name
+		@type name: string
 		
-		@rtype: integer
-		@return: TODO Description
+		@param fx: Uniform value
+		@type fx: float
 		"""
-	def __setUniform1i(val):
+	def setUniform1i(name, ix):
 		"""
-		TODO - Description
+		Set a uniform with an integer value.
 		
-		@param val: the starting frame of the animation
-		@type val: float
-		
-		@rtype: integer
-		@return: TODO Description
+		@param name: the uniform name
+		@type name: string
+
+		@param ix: the uniform value
+		@type ix: integer
 		"""
-	def __setUniform2f(val):
+	def setUniform2f(name, fx, fy):
 		"""
-		TODO - Description
+		Set a uniform with 2 float values
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param name: the uniform name
+		@type name: string
+
+		@param fx: first float value
+		@type fx: float
 		
-		@rtype: integer
-		@return: TODO Description
+		@param fy: second float value
+		@type fy: float
 		"""
-	def __setUniform2i(val):
+	def setUniform2i(name, ix, iy):
 		"""
-		TODO - Description
+		Set a uniform with 2 integer values
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param name: the uniform name
+		@type name: string
+
+		@param ix: first integer value
+		@type ix: integer
 		
-		@rtype: integer
-		@return: TODO Description
+		@param iy: second integer value
+		@type iy: integer
 		"""
-	def __setUniform3f(val):
+	def setUniform3f(name, fx,fy,fz):
 		"""
-		TODO - Description
+		Set a uniform with 3 float values.
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param name: the uniform name
+		@type name: string
+
+		@param fx: first float value
+		@type fx: float
 		
-		@rtype: integer
-		@return: TODO Description
+		@param fy: second float value
+		@type fy: float
+
+		@param fz: third float value
+		@type fz: float
 		"""
-	def __setUniform3i(val):
+	def setUniform3i(name, ix,iy,iz):
 		"""
-		TODO - Description
+		Set a uniform with 3 integer values
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param name: the uniform name
+		@type name: string
+
+		@param ix: first integer value
+		@type ix: integer
+		
+		@param iy: second integer value
+		@type iy: integer
 		
-		@rtype: integer
-		@return: TODO Description
+		@param iz: third integer value
+		@type iz: integer
 		"""
-	def __setUniform4f(val):
+	def setUniform4f(name, fx,fy,fz,fw):
 		"""
-		TODO - Description
+		Set a uniform with 4 float values.
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param name: the uniform name
+		@type name: string
+
+		@param fx: first float value
+		@type fx: float
 		
-		@rtype: integer
-		@return: TODO Description
+		@param fy: second float value
+		@type fy: float
+
+		@param fz: third float value
+		@type fz: float
+
+		@param fw: fourth float value
+		@type fw: float
 		"""
-	def __setUniform4i(val):
+	def setUniform4i(name, ix,iy,iz, iw):
 		"""
-		TODO - Description
+		Set a uniform with 4 integer values
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param name: the uniform name
+		@type name: string
+
+		@param ix: first integer value
+		@type ix: integer
+		
+		@param iy: second integer value
+		@type iy: integer
 		
-		@rtype: integer
-		@return: TODO Description
+		@param iz: third integer value
+		@type iz: integer
+		
+		@param iw: fourth integer value
+		@type iw: integer
 		"""
-	def __setUniformDef(val):
+	def setUniformDef(name, type):
 		"""
-		TODO - Description
+		Define a new uniform
 		
-		@param val: the starting frame of the animation
-		@type val: float
-		
-		@rtype: integer
-		@return: TODO Description
+		@param name: the uniform name
+		@type name: string
+
+		@param type: uniform type
+		@type type: UNI_NONE, UNI_INT, UNI_FLOAT, UNI_INT2, UNI_FLOAT2,	UNI_INT3, UNI_FLOAT3, UNI_INT4,	UNI_FLOAT4,	UNI_MAT3, UNI_MAT4,	UNI_MAX
 		"""
-	def __setUniformMatrix3(val):
+	def setUniformMatrix3(name, mat, transpose):
 		"""
-		TODO - Description
+		Set a uniform with a 3x3 matrix value
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param name: the uniform name
+		@type name: string
+
+		@param mat: A 3x3 matrix [[f,f,f], [f,f,f], [f,f,f]]
+		@type mat: 3x3 matrix
 		
-		@rtype: integer
-		@return: TODO Description
+		@param transpose: set to True to transpose the matrix
+		@type transpose: bool
 		"""
-	def __setUniformMatrix4(val):
+	def setUniformMatrix4(name, mat, transpose):
 		"""
-		TODO - Description
+		Set a uniform with a 4x4 matrix value
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param name: the uniform name
+		@type name: string
+
+		@param mat: A 4x4 matrix [[f,f,f,f], [f,f,f,f], [f,f,f,f], [f,f,f,f]]
+		@type mat: 4x4 matrix
 		
-		@rtype: integer
-		@return: TODO Description
+		@param transpose: set to True to transpose the matrix
+		@type transpose: bool
 		"""
-	def __setUniformiv(val):
+	def setUniformiv(name, iList):
 		"""
-		TODO - Description
+		Set a uniform with a list of integer values
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param name: the uniform name
+		@type name: string
 		
-		@rtype: integer
-		@return: TODO Description
+		@param iList: a list (2, 3 or 4 elements) of integer values
+		@type iList: list[integer]
 		"""
-	def __validate(val):
+	def validate():
 		"""
-		TODO - Description
-		
-		@param val: the starting frame of the animation
-		@type val: float
+		Validate the shader object.
 		
-		@rtype: integer
-		@return: TODO Description
 		"""
diff --git a/source/gameengine/PyDoc/KX_PhysicsObjectWrapper.py b/source/gameengine/PyDoc/KX_PhysicsObjectWrapper.py
index ea9a2a3a411..4cbdbf7cebb 100644
--- a/source/gameengine/PyDoc/KX_PhysicsObjectWrapper.py
+++ b/source/gameengine/PyDoc/KX_PhysicsObjectWrapper.py
@@ -4,46 +4,57 @@ class KX_PhysicsObjectWrapper(PyObjectPlus):
 	"""
 	KX_PhysicsObjectWrapper
 	
-	All placeholders have a __ prefix
 	"""
-	def __setActive(val):
+	def setActive(active):
 		"""
-		TODO - Description
+		Set the object to be active.
 		
-		@param val: the starting frame of the animation
-		@type val: float
-		
-		@rtype: integer
-		@return: TODO Description
+		@param active: set to True to be active
+		@type active: bool
 		"""
 
-	def __setAngularVelocity(val):
+	def setAngularVelocity(x, y, z, local):
 		"""
-		TODO - Description
+		Set the angular velocity of the object.
+		
+		@param x: angular velocity for the x-axis
+		@type x: float
+		
+		@param y: angular velocity for the y-axis
+		@type y: float
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param z: angular velocity for the z-axis
+		@type z: float
 		
-		@rtype: integer
-		@return: TODO Description
+		@param local: set to True for local axis
+		@type local: bool
 		"""
-	def __setLinearVelocity(val):
+	def setLinearVelocity(x, y, z, local):
 		"""
-		TODO - Description
+		Set the linear velocity of the object.
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param x: linear velocity for the x-axis
+		@type x: float
 		
-		@rtype: integer
-		@return: TODO Description
+		@param y: linear velocity for the y-axis
+		@type y: float
+		
+		@param z: linear velocity for the z-axis
+		@type z: float
+		
+		@param local: set to True for local axis
+		@type local: bool
 		"""
-	def __setPosition(val):
+	def setPosition(x, y, z):
 		"""
-		TODO - Description
+		Set the position of the object
+		
+		@param x: x coordinate
+		@type x: float
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param y: y coordinate
+		@type y: float
 		
-		@rtype: integer
-		@return: TODO Description
+		@param z: z coordinate
+		@type z: float
 		"""
diff --git a/source/gameengine/PyDoc/KX_VehicleWrapper.py b/source/gameengine/PyDoc/KX_VehicleWrapper.py
index 3d91b7db676..86991634f2d 100644
--- a/source/gameengine/PyDoc/KX_VehicleWrapper.py
+++ b/source/gameengine/PyDoc/KX_VehicleWrapper.py
@@ -4,13 +4,13 @@ class KX_VehicleWrapper(PyObjectPlus):
 	"""
 	KX_VehicleWrapper
 	
-	All placeholders have a __ prefix
+	TODO - description
 	"""
 	
 	def addWheel(wheel, attachPos, attachDir, axleDir, suspensionRestLength, wheelRadius, hasSteering):
 		
 		"""
-		TODO - Description
+		Add a wheel to the vehicle
 		
 		@param wheel: The object to use as a wheel.
 		@type wheel: L{KX_GameObject<KX_GameObject.KX_GameObject>} or a KX_GameObject name
@@ -26,143 +26,135 @@ class KX_VehicleWrapper(PyObjectPlus):
 		@type wheelRadius: float
 		"""
 
-	def __applyBraking(val):
+	def applyBraking(force, wheelIndex):
 		"""
-		TODO - Description
+		Apply a braking force to the specified wheel
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param force: the brake force
+		@type force: float
 		
-		@rtype: integer
-		@return: TODO Description
+		@param wheelIndex: index of the wheel where the force needs to be applied
+		@type wheelIndex: integer
 		"""
-	def __applyEngineForce(val):
+	def applyEngineForce(force, wheelIndex):
 		"""
-		TODO - Description
+		Apply an engine force to the specified wheel
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param force: the engine force
+		@type force: float
 		
-		@rtype: integer
-		@return: TODO Description
+		@param wheelIndex: index of the wheel where the force needs to be applied
+		@type wheelIndex: integer
 		"""
-	def __getConstraintId(val):
+	def getConstraintId():
 		"""
-		TODO - Description
-		
-		@param val: the starting frame of the animation
-		@type val: float
+		Get the constraint ID
 		
 		@rtype: integer
-		@return: TODO Description
+		@return: the constraint id
 		"""
-	def __getConstraintType(val):
+	def getConstraintType():
 		"""
-		TODO - Description
-		
-		@param val: the starting frame of the animation
-		@type val: float
+		Returns the constraint type.
 		
 		@rtype: integer
-		@return: TODO Description
+		@return: constraint type
 		"""
-	def __getNumWheels(val):
+	def getNumWheels():
 		"""
-		TODO - Description
-		
-		@param val: the starting frame of the animation
-		@type val: float
+		Returns the number of wheels.
 		
 		@rtype: integer
-		@return: TODO Description
+		@return: the number of wheels for this vehicle
 		"""
-	def __getWheelOrientationQuaternion(val):
+	def getWheelOrientationQuaternion(wheelIndex):
 		"""
-		TODO - Description
+		Returns the wheel orientation as a quaternion.
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param wheelIndex: the wheel index
+		@type wheelIndex: integer
 		
-		@rtype: integer
+		@rtype: TODO - type should be quat as per method name but from the code it looks like a matrix
 		@return: TODO Description
 		"""
-	def __getWheelPosition(val):
+	def getWheelPosition(wheelIndex):
 		"""
-		TODO - Description
+		Returns the position of the specified wheel
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param wheelIndex: the wheel index
+		@type wheelIndex: integer
 		
-		@rtype: integer
-		@return: TODO Description
+		@rtype: list[x, y, z]
+		@return: position vector
 		"""
-	def __getWheelRotation(val):
+	def getWheelRotation(wheelIndex):
 		"""
-		TODO - Description
+		Returns the rotation of the specified wheel
 		
-		@param val: the starting frame of the animation
-		@type val: float
+		@param wheelIndex: the wheel index
+		@type wheelIndex: integer
 		
-		@rtype: integer
-		@return: TODO Description
+		@rtype: float
+		@return: the wheel rotation
 		"""
-	def __setRollInfluence(val):
+	def setRollInfluence(rollInfluece, wheelIndex):
 		"""
-		TODO - Description
+		Set the specified wheel's roll influence.
+		The higher the roll influence the more the vehicle will tend to roll over in corners.
 		
-		@param val: the starting frame of the animation
-		@type val: float
-		
-		@rtype: integer
-		@return: TODO Description
+		@param rollInfluece: the wheel roll influence
+		@type rollInfluece: float
+
+		@param wheelIndex: the wheel index
+		@type wheelIndex: integer
 		"""
-	def __setSteeringValue(val):
+	def setSteeringValue(steering, wheelIndex):
 		"""
-		TODO - Description
-		
-		@param val: the starting frame of the animation
-		@type val: float
+		Set the specified wheel's steering
 		
-		@rtype: integer
-		@return: TODO Description
+		@param steering: the wheel steering
+		@type steering: float
+
+		@param wheelIndex: the wheel index
+		@type wheelIndex: integer
 		"""
-	def __setSuspensionCompression(val):
+	def setSuspensionCompression(compression, wheelIndex):
 		"""
-		TODO - Description
+		Set the specified wheel's compression
 		
-		@param val: the starting frame of the animation
-		@type val: float
-		
-		@rtype: integer
-		@return: TODO Description
+		@param compression: the wheel compression
+		@type compression: float
+
+		@param wheelIndex: the wheel index
+		@type wheelIndex: integer
 		"""
-	def __setSuspensionDamping(val):
+	def setSuspensionDamping(damping, wheelIndex):
 		"""
-		TODO - Description
-		
-		@param val: the starting frame of the animation
-		@type val: float
+		Set the specified wheel's damping
 		
-		@rtype: integer
-		@return: TODO Description
+		@param damping: the wheel damping
+		@type damping: float
+
+		@param wheelIndex: the wheel index
+		@type wheelIndex: integer
 		"""
-	def __setSuspensionStiffness(val):
+	def setSuspensionStiffness(stiffness, wheelIndex):
 		"""
-		TODO - Description
-		
-		@param val: the starting frame of the animation
-		@type val: float
+		Set the specified wheel's stiffness
 		
-		@rtype: integer
-		@return: TODO Description
+		@param stiffness: the wheel stiffness
+		@type stiffness: float
+
+		@param wheelIndex: the wheel index
+		@type wheelIndex: integer
 		"""
-	def __setTyreFriction(val):
+	def setTyreFriction(friction, wheelIndex):
 		"""
-		TODO - Description
+		Set the specified wheel's tyre friction
 		
-		@param val: the starting frame of the animation
-		@type val: float
-		
-		@rtype: integer
-		@return: TODO Description
+		@param friction: the tyre friction
+		@type friction: float
+
+		@param wheelIndex: the wheel index
+		@type wheelIndex: integer
 		"""
diff --git a/source/gameengine/PyDoc/epy_docgen.sh b/source/gameengine/PyDoc/epy_docgen.sh
index ddf39dcc081..0872d2abbbd 100755
--- a/source/gameengine/PyDoc/epy_docgen.sh
+++ b/source/gameengine/PyDoc/epy_docgen.sh
@@ -8,4 +8,4 @@
 LC_ALL=POSIX
 
 epydoc --debug -v  -o BPY_GE --url "http://www.blender.org" --top GameLogic \
- --name "Blender GameEngine" --no-private --no-frames --no-sourcecode --inheritance=included *.py 
+ --name "Blender GameEngine" --no-private --no-sourcecode --inheritance=included *.py