BGE EPY Docs: PhysicsConstraints and fixes in other modules

PhysicsConstraints module documented by Jean-François (Ninja Goliath) based on GameKit 2nd ed.
Thanks for the initiative and the great help!

General advice for anyone helping with EpyDocs:
* use :: instead of : to keep the indentation correct,
* use B{} for clarity when needed (e.g. createConstraints)

Adding F13 to F19 to complement Matt's recent commit
* There are other (not so important) functions in PhysicsConstraints module that are not exposed in the documentation right now.

The generated page is temporarily here, if someone want to review it:
http://blenderecia.orgfree.com/blender/tmp/PhysicsConstraints-module.html

5 files changed, 301 insertions, 116 deletions

diff --git a/source/gameengine/PyDoc/GameKeys.py b/source/gameengine/PyDoc/GameKeys.py
index 8e5c7d3ae24..1c4f45ddbab 100644
--- a/source/gameengine/PyDoc/GameKeys.py
+++ b/source/gameengine/PyDoc/GameKeys.py
@@ -13,7 +13,7 @@ Example::
 	
 	co = GameLogic.getCurrentController()
 	# 'Keyboard' is a keyboard sensor
-	sensor = co.getSensor('Keyboard')
+	sensor = co.sensors["Keyboard"]
 	sensor.key = GameKeys.F1KEY
 
 Example::
@@ -23,18 +23,18 @@ Example::
 	
 	co = GameLogic.getCurrentController()
 	# 'Keyboard' is a keyboard sensor
-	sensor = co.getSensor('Keyboard')
-	keylist = sensor.events
-	for key in keylist:
+	sensor = co.sensors["Keyboard"]
+
+	for key,status in sensor.events:
 		# key[0] == GameKeys.keycode, key[1] = status
-		if key[1] == GameLogic.KX_INPUT_JUST_ACTIVATED:
-			if key[0] == GameKeys.WKEY:
+		if status == GameLogic.KX_INPUT_JUST_ACTIVATED:
+			if key == GameKeys.WKEY:
 				# Activate Forward!
-			if key[0] == GameKeys.SKEY:
+			if key == GameKeys.SKEY:
 				# Activate Backward!
-			if key[0] == GameKeys.AKEY:
+			if key == GameKeys.AKEY:
 				# Activate Left!
-			if key[0] == GameKeys.DKEY:
+			if key == GameKeys.DKEY:
 				# Activate Right!
 
 @group Alphabet keys: AKEY, BKEY, CKEY, DKEY, EKEY, FKEY, GKEY, HKEY, IKEY, JKEY, KKEY, LKEY, MKEY, NKEY, OKEY, PKEY, QKEY, RKEY, SKEY, TKEY, UKEY, VKEY, WKEY, XKEY, YKEY, ZKEY
@@ -110,7 +110,7 @@ Example::
 @var PADENTER:
 @var PADPLUSKEY:
 
-@group Function Keys: F1KEY, F2KEY, F3KEY, F4KEY, F5KEY, F6KEY, F7KEY, F8KEY, F9KEY, F10KEY, F11KEY, F12KEY
+@group Function Keys: F1KEY, F2KEY, F3KEY, F4KEY, F5KEY, F6KEY, F7KEY, F8KEY, F9KEY, F10KEY, F11KEY, F12KEY, F13KEY, F14KEY, F15KEY, F16KEY, F17KEY, F18KEY, F19KEY
 @var F1KEY:
 @var F2KEY:
 @var F3KEY:
@@ -123,6 +123,13 @@ Example::
 @var F10KEY:
 @var F11KEY:
 @var F12KEY:
+@var F13KEY:
+@var F14KEY:
+@var F15KEY:
+@var F16KEY:
+@var F17KEY:
+@var F18KEY:
+@var F19KEY:
 
 @group Other Keys: ACCENTGRAVEKEY, BACKSLASHKEY, BACKSPACEKEY, COMMAKEY, DELKEY, ENDKEY, EQUALKEY, ESCKEY, HOMEKEY, INSERTKEY, LEFTBRACKETKEY, LINEFEEDKEY, MINUSKEY, PAGEDOWNKEY, PAGEUPKEY, PAUSEKEY, PERIODKEY, QUOTEKEY, RIGHTBRACKETKEY, RETKEY, SEMICOLONKEY, SLASHKEY, SPACEKEY, TABKEY
 @var ACCENTGRAVEKEY:
diff --git a/source/gameengine/PyDoc/GameLogic.py b/source/gameengine/PyDoc/GameLogic.py
index 4bef65e42b3..5eb0fecd94c 100644
--- a/source/gameengine/PyDoc/GameLogic.py
+++ b/source/gameengine/PyDoc/GameLogic.py
@@ -361,8 +361,8 @@ def addScene(name, overlay=1):
 	
 	@param name: The name of the scene
 	@type name: string
-	@param body: Overlay or underlay (optional)
-	@type body: int
+	@param overlay: Overlay or underlay (optional)
+	@type overlay: int
 	"""
 def sendMessage(subject, body="", to="", message_from=""):
 	"""
@@ -402,7 +402,7 @@ def getMaxLogicFrame():
 	Gets the maximum number of logic frame per render frame.
 	
 	@return: The maximum number of logic frame per render frame
-	@rtype: interger
+	@rtype: integer
 	"""
 def setMaxLogicFrame(maxlogic):
 	"""
@@ -417,7 +417,7 @@ def getMaxPhysicsFrame():
 	Gets the maximum number of physics frame per render frame.
 	
 	@return: The maximum number of physics frame per render frame
-	@rtype: interger
+	@rtype: integer
 	"""
 def setMaxPhysicsFrame(maxphysics):
 	"""
diff --git a/source/gameengine/PyDoc/GameTypes.py b/source/gameengine/PyDoc/GameTypes.py
index 45d08d2e96a..22915de37c7 100644
--- a/source/gameengine/PyDoc/GameTypes.py
+++ b/source/gameengine/PyDoc/GameTypes.py
@@ -108,7 +108,7 @@ class SCA_ILogicBrick(CValue):
 		"""
 #}
 
-class SCA_PythonKeyboard(PyObjectPlus)
+class SCA_PythonKeyboard(PyObjectPlus):
 	"""
 	The current keyboard.	
 	@ivar events: a list of pressed keys that have either been pressed, or just released, or are active this frame. (read-only).
@@ -124,7 +124,7 @@ class SCA_PythonKeyboard(PyObjectPlus)
 	"""
 	pass
 	
-class SCA_PythonMouse(PyObjectPlus)
+class SCA_PythonMouse(PyObjectPlus):
 	"""
 	The current mouse.
 	
diff --git a/source/gameengine/PyDoc/PhysicsConstraints.py b/source/gameengine/PyDoc/PhysicsConstraints.py
index d78a32f4f79..2859aedd2d1 100644
--- a/source/gameengine/PyDoc/PhysicsConstraints.py
+++ b/source/gameengine/PyDoc/PhysicsConstraints.py
@@ -1,126 +1,294 @@
 # $Id$
 """
 Documentation for the PhysicsConstraints module.
+================================================
 
-Example:
+Example::
+	
+	
+	#  Adding a point constraint  #
+	###############################
+	
+	
+	# import BGE internal module
+	import PhysicsConstraints
+	
+	# get object list
+	obj_list = GameLogic.getCurrentScene().objects
+	
+	# get object named Obj_1
+	root = obj_list["root"]
+	obj = obj_list["obj"]
+
+	# get object physics ID
+	phido = obj.getPhysicsId()
+	
+	# get root physics ID
+	phidr = root.getPhysicsId()
+
+	# want to use point constraint type
+	constraint_type = 1
+	
+	# Use bottom right front corner of object for point constraint position
+	point_pos_x = 1.0
+	point_pos_y = -1.0
+	point_pos_z = -1.0
+	
+	# create a point constraint
+	const =	PhysicsConstraints.createConstraint( phido, phidr, constraint_type, point_pos_x, point_pos_y, point_pos_z)
+
+	# stores the new constraint ID to be used later
+	obj["constraint_ID"] = const.getConstraintId()	
+	
+	
+Example::
+	
+	
+	#  Removing a point constraint  #
+	#################################
+	
+	
+	# import BGE internal module
 	import PhysicsConstraints
-	import GameLogic
+	
+	# get object list
+	obj_list = GameLogic.getCurrentScene().objects
+	
+	# get object 1
+	obj = obj_list["obj"]
+	
+	# get constraint ID that was saved as an obj property
+	# when the constraint was created
+	constraint_ID = obj["constraint_ID"]
+	
+	# remove constraint
+	PhysicsConstraints.removeConstraint(constraint_ID)
 
 """
-# TODO
-# error
 
-def createConstraint():
-	"""
-	Does something
+def createConstraint(obj_PhysicsID, root_PhysicsID, constraintType, pointPos_x, pointPos_y, pointPos_z, edgePos_x, edgePos_y, edgePos_z, edgeAngle_x, edgeAngle_y, edgeAngle_z):
+	"""	
+	Create a point constraint between two objects, an edge constraint between two objects, or a vehicle constraint on an object.
 	
-	@rtype: 
-	"""
-def getAppliedImpulse():
-	"""
-	Does something
+	You only have to input the needed parammeters depending on the type of constraint you are trying to create.
 	
-	@rtype: 
-	"""
-def getVehicleConstraint():
-	"""
-	Does something
+
+	B{Point Constraint} ::
 	
-	@rtype: 
-	"""
-def removeConstraint():
-	"""
-	Does something
+		While creating a point constraint, the "pointPos" values define where you want the pivot point to be located.
+		If you are creating a point constraint be sure to assing the integer "1" as the constraintType value.
 	
-	@rtype: 
-	"""
-def setCcdMode():
-	"""
-	Does something
+		Parameters to use:
+		obj_PhysicsID, root_PhysicsID, constraintType, pointPos_x, pointPos_y, pointPos_z
 	
-	@rtype: 
-	"""
-def setContactBreakingTreshold():
-	"""
-	Does something
+	B{Edge Constraint} ::
+		
+		While creating an edge constraint, the "edgePos" values define where you want the center of the edge constraint to be.
+		Also, the "edgeAngle" values define in which direction you want the edge constraint to point (As a 3 dimensions vector).
+		If you want to create an edge constraint be sure to assing the integer "2" as the constraintType value.
+
+		Parameters to use:
+		obj_PhysicsID, root_PhysicsID, constraintType, edgePos_x, edgePos_y, edgePos_z, edgeAngle_x, edgeAngle_y, edgeAngle_z}		
 	
-	@rtype: 
-	"""
-def setDeactivationAngularTreshold():
-	"""
-	Does something
+	B{Vehicle Constraint} ::
+		
+		While creating a point constraint, the "pointPos" values define where you want the pivot point to be located.
+		If you want to create an edge constraint be sure to assing the integer "0" as the constraintType value.
+
+		Parameters to use :
+		obj_PhysicsID, root_PhysicsID, constraintType
 	
-	@rtype: 
-	"""
-def setDeactivationLinearTreshold():
+	@type obj_PhysicsID: integer
+	@param obj_PhysicsID: The physic ID of the first object to constraint.
+
+	@type root_PhysicsID: integer
+	@param root_PhysicsID: The physic ID of the second object to constraint.
+
+	@type constraintType: integer
+	@param constraintType: The type of constraint.
+
+	@type pointPos_x: float
+	@param pointPos_x: The X position of the point constraint.
+
+	@type pointPos_y: float
+	@param pointPos_y: The Y position of the point constraint.
+
+	@type pointPos_z: float
+	@param pointPos_z: The Z position of the point constraint.
+
+	@type edgePos_x: float
+	@param edgePos_x: The X value of the center of the edge constraint.
+
+	@type edgePos_y: float
+	@param edgePos_y: The Y value of the center of the edge constraint.
+
+	@type edgePos_z: float
+	@param edgePos_z: The Z value of the center of the edge constraint.
+
+	@type edgeAngle_x: float
+	@param edgeAngle_x: The X value of the edge's orientation vector.
+
+	@type edgeAngle_y: float
+	@param edgeAngle_y: The Y value of the edge's orientation vector.
+
+	@type edgeAngle_z: float
+	@param edgeAngle_z: The Z value of the edge's orientation vector.
+
+	@rtype: integer
+	@return: The created constraint ID
 	"""
-	Does something
 	
-	@rtype: 
-	"""
-def setDeactivationTime():
+
+def getAppliedImpulse(constraint_ID):
 	"""
-	Does something
+	Returns the applied impulse.
 	
-	@rtype: 
+	@param constraint_ID: The constraint ID that was saved on the creation of the constraint.
+	@type constraint_ID: integer
+	@rtype: float
+	@return: Measure the stress on a constraint.
 	"""
-def setDebugMode():
+
+
+def getVehicleConstraint(constraint_ID):
 	"""
-	Does something
+	Returns the vehicle constraint ID.
 	
-	@rtype: 
+	@param constraint_ID: The constraint ID that was saved on the creation of the constraint.
+	@type constraint_ID: integer
+	@rtype: integer
 	"""
-def setGravity():
+def removeConstraint(constraint_ID):
 	"""
-	Does something
 	
-	@rtype: 
-	"""
-def setLinearAirDamping():
-	"""
-	Does something
+	Removes the constraint between 2 game objects (point and edge constraints).
+	
+	It does not remove vehicle constraints.
 	
-	@rtype: 
+	@param constraint_ID: The constraint ID that was saved on the creation of the constraint.
+	@type constraint_ID: integer
 	"""
-def setNumIterations():
+def setDeactivationLinearTreshold(linearTreshold):
 	"""
-	Does something
 	
-	@rtype: 
+	Sets the linear velocity that an object must be below before the deactivation timer can start.
+	
+	This affects every object in the scene, except for game objects that have 'No sleeping' turned on.
+	
+	@param linearTreshold: The linear velocity.
+	@type linearTreshold: float
 	"""
-def setNumTimeSubSteps():
+def setDeactivationAngularTreshold(angularTreshold):
 	"""
-	Does something
 	
-	@rtype: 
+	Sets the angular velocity that an object must be below before the deactivation timer can start.
+	
+	This affects every object in the scene, except for game objects that have 'No sleeping' turned on.
+	
+	@param angularTreshold: The angular velocity.
+	@type angularTreshold: float
 	"""
-def setSolverDamping():
+def setDeactivationTime(time):
 	"""
-	Does something
 	
-	@rtype: 
+	Time (in seconds) after objects with velocity less then thresholds (see below) are deactivated.
+	
+	This affects every object in the scene, except for game objects that have 'No sleeping' turned on.
+	
+	This function is directly related with the 2 above functions.
+	
+	
+	@param time: The time in seconds.
+	@type time: float
 	"""
-def setSolverTau():
+def setGravity(gx, gy, gz):
 	"""
-	Does something
+	Sets the gravity for the actual scene only.
+	
+	All other scenes remain unaffected.
 	
-	@rtype: 
+	This affects every object in the scene that has physics enabled.
+	
+	@param gx: The force of gravity on world x axis.
+	@type gx: float
+	@param gy: The force of gravity on world y axis.
+	@type gy: float
+	@param gz: The force of gravity on world z axis.
+	@type gz: float
 	"""
-def setSolverType():
+def setLinearAirDamping(damping):
 	"""
-	Does something
 	
-	@rtype: 
+	Sets the linear air resistance for all objects in the scene.
+	
+	@param damping: The linear air resistance.
+	@type damping: float
 	"""
-def setSorConstant():
+def setNumIterations(numIter):
 	"""
-	Does something
+	Sets the number of times an iterative constraint solver is repeated.
 	
-	@rtype: 
+	Increasing the number of iterations improves the constraint solver at the cost of performances & the speed of the game engine.
+	
+	@param numIter: The number of timesubsteps. (Input 0 to suspend simulation numSubStep)
+	@type numIter: integer
 	"""
-def setUseEpa():
+def setNumTimeSubSteps(numSubStep):
 	"""
-	Does something
+	Set the quality of the entire physics simulation including collision detection and constraint solver.
+	
+	Increase the number of time substeps to improves the quality of the entire physics simulation at the cost of the performance & the speed of the game engine.
 	
-	@rtype: 
-	"""
\ No newline at end of file
+	@param numSubStep: The number of timesubsteps. (Input 0 to suspend simulation numSubStep)
+	@type numSubStep: integer
+	"""
+#def setDebugMode():
+#	"""
+#	
+#	
+#	
+#	@param numIter: 
+#	@type numIter: 
+#	"""
+#def setCcdMode():
+#	"""
+#	Does something
+#	
+#	@rtype: 
+#	"""
+#def setContactBreakingTreshold():
+#	"""
+#	Does something
+#	
+#	@rtype: 
+#	"""
+#def setSolverDamping():
+#	"""
+#	Does something
+#	
+#	@rtype: 
+#	"""
+#def setSolverTau():
+#	"""
+#	Does something
+#	
+#	@rtype: 
+#	"""
+#def setSolverType():
+#	"""
+#	Does something
+#	
+#	@rtype: 
+#	"""
+#def setSorConstant():
+#	"""
+#	Does something
+#	
+#	@rtype: 
+#	"""
+#def setUseEpa():
+#	"""
+#	Does something
+#	
+#	@rtype: 
+#	"""
\ No newline at end of file
diff --git a/source/gameengine/PyDoc/VideoTexture.py b/source/gameengine/PyDoc/VideoTexture.py
index 73809a7a15c..186d621557f 100644
--- a/source/gameengine/PyDoc/VideoTexture.py
+++ b/source/gameengine/PyDoc/VideoTexture.py
@@ -1,32 +1,38 @@
 # $Id$
 """
-The VideoTexture module allows you to manipulate textures during the game. 
+The VideoTexture module allows you to manipulate textures during the game.
+
 Several sources for texture are possible: video files, image files, 
-video capture, memory buffer, camera render or a mix of that. 
+video capture, memory buffer, camera render or a mix of that.
+
 The video and image files can be loaded from the internet using an URL 
-instead of a file name. In addition, you can apply filters on the images
-before sending them to the GPU, allowing video effect: blue screen, 
-color band, gray, normal map. 
+instead of a file name.
+
+In addition, you can apply filters on the images before sending them to the GPU, allowing video effect: blue screen, 
+color band, gray, normal map.
+
 VideoTexture uses FFmpeg to load images and videos. All the formats and codecs
-that FFmpeg supports are supported by VideoTexture, including but not limited to: 
+that FFmpeg supports are supported by VideoTexture, including but not limited to::
 
-    * AVI
-    * Ogg
-    * Xvid
-    * Theora
-    * dv1394 camera
-    * video4linux capture card (this includes many webcams)
-    * videoForWindows capture card (this includes many webcams)
-    * JPG 
+	* AVI
+	* Ogg
+	* Xvid
+	* Theora
+	* dv1394 camera
+	* video4linux capture card (this includes many webcams)
+	* videoForWindows capture card (this includes many webcams)
+	* JPG 
 
 The principle is simple: first you identify a texture on an existing object using 
 the L{materialID} function, then you create a new texture with dynamic content
-and swap the two textures in the GPU. 
+and swap the two textures in the GPU.
+
 The GE is not aware of the substitution and continues to display the object as always, 
-except that you are now in control of the texture. When the texture object is deleted,
-the new texture is deleted and the old texture restored. 
+except that you are now in control of the texture.
 
-Example:
+When the texture object is deleted, the new texture is deleted and the old texture restored. 
+
+Example::
 	import VideoTexture
 	import GameLogic
 
@@ -71,15 +77,18 @@ def imageToArray(image,mode):
 	@param mode: optional argument representing the pixel format. 
 	             You can use the characters R, G, B for the 3 color channels, A for the alpha channel, 
 	             0 to force a fixed 0 color channel and 1 to force a fixed 255 color channel.
-	             Example: "BGR" will return 3 bytes per pixel with the Blue, Green and Red channels in that order. 
+	             Example: "BGR" will return 3 bytes per pixel with the Blue, Green and Red channels in that order. \
 	                      "RGB1" will return 4 bytes per pixel with the Red, Green, Blue channels in that order and the alpha channel forced to 255.
 	             The default mode is "RGBA".
 	@type mode: string
-	@rtype: BGL.buffer object representing the image as one dimensional array of bytes of size (pixel_size*width*height), line by line starting from the bottom of the image. The pixel size and format is determined by the mode parameter.
+	@rtype: BGL.buffer
+	@returns: object representing the image as one dimensional array of bytes of size (pixel_size*width*height), line by line starting from the bottom of the image. The pixel size and format is determined by the mode parameter.
 	"""
+
 def materialID(object,name):
 	"""
 	Returns a numeric value that can be used in L{Texture} to create a dynamic texture.
+
 	The value corresponds to an internal material number that uses the texture identified
 	by name. name is a string representing a texture name with IM prefix if you want to
 	identify the texture directly. 	This method works for basic tex face and for material,
@@ -87,6 +96,7 @@ def materialID(object,name):
 	position of the texture stack. 	name can also have MA prefix if you want to identify
 	the texture by material. In that case the material must have a texture channel in first
 	position.
+	
 	If the object has no material that matches name, it generates a runtime error. Use try/except to catch the exception.
 	
 	Ex: VideoTexture.materialID(obj, 'IMvideo.png')
@@ -198,7 +208,7 @@ def Texture():
 	"""
 	Does something
 	
-	@rtype: 
+	@rtype: L{Texture}
 	"""
 def VideoFFmpeg():
 	"""