Update bge.constraints API doc

D1357 by @Matpi with edits.

1 files changed, 70 insertions, 101 deletions

diff --git a/doc/python_api/rst/bge.constraints.rst b/doc/python_api/rst/bge.constraints.rst
index b7df227400b..e47625d44fc 100644
--- a/doc/python_api/rst/bge.constraints.rst
+++ b/doc/python_api/rst/bge.constraints.rst
@@ -4,75 +4,76 @@ Physics Constraints (bge.constraints)
 
 .. module:: bge.constraints
 
-.. literalinclude:: ../examples/bge.constraints.py
-   :language: rest
-   :lines: 2-4
+.. include:: ../examples/bge.constraints.py
+   :start-line: 1
+   :end-line: 4
 
 .. literalinclude:: ../examples/bge.constraints.py
    :lines: 6-
 
-.. function:: createConstraint(physicsid_1, physicsid_2, constraint_type, pivot_X, pivot_y, pivot_z, axis_x, axis_y, axis_z, flag)
+.. function:: createConstraint( \
+      physicsid_1, physicsid_2, constraint_type, \
+      pivot_x=0.0, pivot_y=0.0, pivot_z=0.0, \
+      axis_x=0.0, axis_y=0.0, axis_z=0.0, flag=0)
 
    Creates a constraint.
 
-   Constraints types:
+   :arg physicsid_1: The physics id of the first object in constraint.
+   :type physicsid_1: int
+
+   :arg physicsid_2: The physics id of the second object in constraint.
+   :type physicsid_2: int
+
+   :arg constraint_type: The type of the constraint, one of...
+
       - :class:`POINTTOPOINT_CONSTRAINT`
       - :class:`LINEHINGE_CONSTRAINT`
       - :class:`ANGULAR_CONSTRAINT`
       - :class:`CONETWIST_CONSTRAINT`
       - :class:`VEHICLE_CONSTRAINT`
-      - :class:`GENERIC_6DOF_CONSTRAINT` 
-
-   :arg physicsid_1: the physics id of the first object in constraint.
-   :type physicsid_1: int
-
-   :arg physicsid_2: the physics id of the second object in constraint.
-   :type physicsid_2: int
+      - :class:`GENERIC_6DOF_CONSTRAINT`
 
-   :arg constraint_type: the type of the constraint.
    :type constraint_type: int
 
-   :arg pivot_x: pivot X position (optional).
+   :arg pivot_x: Pivot X position. (optional)
    :type pivot_x: float
 
-   :arg pivot_y: pivot Y position (optional).
+   :arg pivot_y: Pivot Y position. (optional)
    :type pivot_y: float
 
-   :arg pivot_z: pivot Z position (optional).
+   :arg pivot_z: Pivot Z position. (optional)
    :type pivot_z: float
 
-   :arg axis_x: X axis angle in degrees (optional).
+   :arg axis_x: X axis angle in degrees. (optional)
    :type axis_x: float
 
-   :arg axis_y: Y axis angle in degrees (optional).
+   :arg axis_y: Y axis angle in degrees. (optional)
    :type axis_y: float
 
-   :arg axis_z: Z axis angle in degrees (optional).
+   :arg axis_z: Z axis angle in degrees. (optional)
    :type axis_z: float
 
-   :arg flag: 128 to disable collision between linked bodies (optional).
+   :arg flag: 128 to disable collision between linked bodies. (optional)
    :type flag: int
 
-   :return: a constraint wrapper.
-   :rtype: :class:`bge.types.KX_ConstraintWrapper`
-
-.. attribute:: error
-
-   Symbolic constant string that indicates error.
+   :return: A constraint wrapper.
+   :rtype: :class:`~bge.types.KX_ConstraintWrapper`
 
 .. function:: exportBulletFile(filename)
 
-   export a .bullet file
+   Exports a file representing the dynamics world (usually using ``.bullet`` extension).
+
+   See `Bullet binary serialization <http://bulletphysics.org/mediawiki-1.5.8/index.php/Bullet_binary_serialization>`__.
 
-   :arg filename: File name
-   :type filename: string
+   :arg filename: Absolute filepath.
+   :type filename: str
 
 .. function:: getAppliedImpulse(constraintId)
 
    :arg constraintId: The id of the constraint.
    :type constraintId: int
 
-   :return: the most recent applied impulse.
+   :return: The most recent applied impulse.
    :rtype: float
 
 .. function:: getVehicleConstraint(constraintId)
@@ -80,16 +81,16 @@ Physics Constraints (bge.constraints)
    :arg constraintId: The id of the vehicle constraint.
    :type constraintId: int
 
-   :return: a vehicle constraint object.
-   :rtype: :class:`bge.types.KX_VehicleWrapper`
+   :return: A vehicle constraint object.
+   :rtype: :class:`~bge.types.KX_VehicleWrapper`
 
 .. function:: getCharacter(gameobj)
 
    :arg gameobj: The game object with the character physics.
-   :type gameobj: :class:`bge.types.KX_GameObject`
+   :type gameobj: :class:`~bge.types.KX_GameObject`
 
-   :return: character wrapper
-   :rtype: :class:`bge.types.KX_CharacterWrapper`
+   :return: Character wrapper.
+   :rtype: :class:`~bge.types.KX_CharacterWrapper`
 
 .. function:: removeConstraint(constraintId)
 
@@ -143,7 +144,8 @@ Physics Constraints (bge.constraints)
 
    Sets the debug mode.
 
-   Debug modes:
+   :arg mode: The new debug mode.
+
       - :class:`DBG_NODEBUG`
       - :class:`DBG_DRAWWIREFRAME`
       - :class:`DBG_DRAWAABB`
@@ -159,7 +161,6 @@ Physics Constraints (bge.constraints)
       - :class:`DBG_DRAWCONSTRAINTLIMITS`
       - :class:`DBG_FASTWIREFRAME`
 
-   :arg mode: The new debug mode.
    :type mode: int
 
 .. function:: setGravity(x, y, z)
@@ -178,7 +179,8 @@ Physics Constraints (bge.constraints)
 .. function:: setLinearAirDamping(damping)
 
    .. note::
-      Not implemented.
+
+      Not implemented
 
    Sets the linear air damping for rigidbodies.
 
@@ -238,144 +240,111 @@ Physics Constraints (bge.constraints)
 
 .. function:: setUseEpa(epa)
 
-   Not implemented.
+   .. note::
 
-.. data:: DBG_NODEBUG
+      Not implemented
 
-   .. note::
-      Debug mode to be used with function :class:`setDebugMode`
+
+Constants
++++++++++
+
+.. attribute:: error
+
+   Symbolic constant string that indicates error.
+
+   :type: str
+
+
+Debug Mode Constants
+^^^^^^^^^^^^^^^^^^^^
+
+Debug mode to be used with :func:`setDebugMode`
+
+
+.. data:: DBG_NODEBUG
 
    No debug.
 
 .. data:: DBG_DRAWWIREFRAME
 
-   .. note::
-      Debug mode to be used with function :class:`setDebugMode`
-
    Draw wireframe in debug.
 
 .. data:: DBG_DRAWAABB
 
-   .. note::
-      Debug mode to be used with function :class:`setDebugMode`
-
    Draw Axis Aligned Bounding Box in debug.
 
 .. data:: DBG_DRAWFREATURESTEXT
 
-   .. note::
-      Debug mode to be used with function :class:`setDebugMode`
-
-   Draw freatures text in debug.
+   Draw features text in debug.
 
 .. data:: DBG_DRAWCONTACTPOINTS
 
-   .. note::
-      Debug mode to be used with function :class:`setDebugMode`
-
    Draw contact points in debug.
 
 .. data:: DBG_NOHELPTEXT
 
-   .. note::
-      Debug mode to be used with function :class:`setDebugMode`
-
    Debug without help text.
 
 .. data:: DBG_DRAWTEXT
 
-   .. note::
-      Debug mode to be used with function :class:`setDebugMode`
-
    Draw text in debug.
 
 .. data:: DBG_PROFILETIMINGS
 
-   .. note::
-      Debug mode to be used with function :class:`setDebugMode`
-
    Draw profile timings in debug.
 
 .. data:: DBG_ENABLESATCOMPARISION
 
-   .. note::
-      Debug mode to be used with function :class:`setDebugMode`
-
    Enable sat comparision in debug.
 
 .. data:: DBG_DISABLEBULLETLCP
 
-   .. note::
-      Debug mode to be used with function :class:`setDebugMode`
-
    Disable Bullet LCP.
 
 .. data:: DBG_ENABLECCD
 
-   .. note::
-      Debug mode to be used with function :class:`setDebugMode`
-
-   Enable Continous Colision Detection in debug.
+   Enable Continous Collision Detection in debug.
 
 .. data:: DBG_DRAWCONSTRAINTS
 
-   .. note::
-      Debug mode to be used with function :class:`setDebugMode`
-
    Draw constraints in debug.
 
 .. data:: DBG_DRAWCONSTRAINTLIMITS
 
-   .. note::
-      Debug mode to be used with function :class:`setDebugMode`
-
    Draw constraint limits in debug.
 
 .. data:: DBG_FASTWIREFRAME
 
-   .. note::
-      Debug mode to be used with function :class:`setDebugMode`
-
    Draw a fast wireframe in debug.
 
-.. data:: POINTTOPOINT_CONSTRAINT
 
-   .. note::
-      Constraint type to be used with function :class:`createConstraint`
+Create Constraint Constants
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Constraint type to be used with :func:`createConstraint`
+
+
+.. data:: POINTTOPOINT_CONSTRAINT
 
    .. to do
 
 .. data:: LINEHINGE_CONSTRAINT
 
-   .. note::
-      Constraint type to be used with function :class:`createConstraint`
-
    .. to do
 
 .. data:: ANGULAR_CONSTRAINT
 
-   .. note::
-      Constraint type to be used with function :class:`createConstraint`
-
    .. to do
 
 .. data:: CONETWIST_CONSTRAINT
 
-   .. note::
-       Constraint type to be used with function :class:`createConstraint`
-
    .. to do
 
 .. data:: VEHICLE_CONSTRAINT
 
-   .. note::
-      Constraint type to be used with function :class:`createConstraint`
-
    .. to do
 
 .. data:: GENERIC_6DOF_CONSTRAINT
 
-   .. note::
-      Constraint type to be used with function :class:`createConstraint`
-
    .. to do
+