* Mathutils attributes documented - http://www.blender.org/documentation/250PythonDoc/Mathutils.html

* Vector.difference() needed normalized vectors
* bpy.DEUBG -> bpy.app.debug

11 files changed, 162 insertions, 167 deletions

diff --git a/release/scripts/modules/bpy/__init__.py b/release/scripts/modules/bpy/__init__.py
index a6bb2921a34..1b248658afd 100644
--- a/release/scripts/modules/bpy/__init__.py
+++ b/release/scripts/modules/bpy/__init__.py
@@ -35,8 +35,6 @@ from bpy import ops as _ops_module
 ops = _ops_module.ops_fake_module
 
 import sys as _sys
-DEBUG = ("-d" in _sys.argv)
-
 
 def load_scripts(reload_scripts=False):
     import os
@@ -58,7 +56,7 @@ def load_scripts(reload_scripts=False):
         try:
             t = time.time()
             ret = __import__(module_name)
-            if DEBUG:
+            if app.debug:
                 print("time %s %.4f" % (module_name, time.time() - t))
             return ret
         except:
@@ -104,7 +102,7 @@ def load_scripts(reload_scripts=False):
                         print("Reloading:", mod)
                         test_reload(mod)
 
-    if DEBUG:
+    if app.debug:
         print("Time %.4f" % (time.time() - t_main))
 
 
diff --git a/release/scripts/modules/bpy/app.py b/release/scripts/modules/bpy/app.py
index 8fc92175d0e..7b4b5e03ab7 100644
--- a/release/scripts/modules/bpy/app.py
+++ b/release/scripts/modules/bpy/app.py
@@ -38,10 +38,16 @@ This module contains application values that remain unchanged during runtime.
 
    The location of blenders executable, useful for utilities that spawn new instances.
 
+.. data:: debug
+
+   Boolean, set when blender is running in debug mode (started with -d)
+
 """
 # constants
 import _bpy
+import sys as _sys
 version = _bpy._VERSION
 version_string = _bpy._VERSION_STR
 home = _bpy._HOME
 binary_path = _bpy._BINPATH
+debug = ("-d" in _sys.argv)
diff --git a/source/blender/blenlib/intern/math_rotation.c b/source/blender/blenlib/intern/math_rotation.c
index 61d5eeaaa2c..ef48b29ae21 100644
--- a/source/blender/blenlib/intern/math_rotation.c
+++ b/source/blender/blenlib/intern/math_rotation.c
@@ -327,6 +327,7 @@ void normalize_qt(float *q)
 	}
 }
 
+/* note: expects vectors to be normalized */
 void rotation_between_vecs_to_quat(float *q, const float v1[3], const float v2[3])
 {
 	float axis[3];
diff --git a/source/blender/python/doc/epy/Mathutils.py b/source/blender/python/doc/epy/Mathutils.py
index 8cd78920f08..eff3ab87dd3 100644
--- a/source/blender/python/doc/epy/Mathutils.py
+++ b/source/blender/python/doc/epy/Mathutils.py
@@ -33,15 +33,6 @@ class Vector:
   """
   The Vector object
   =================
-    This object gives access to Vectors in Blender.
-  @group Axises: x, y, z, w
-  @ivar x: The x value.
-  @ivar y: The y value.
-  @ivar z: The z value (if any).
-  @ivar w: The w value (if any).
-  @ivar length: The magnitude of the vector.
-  @ivar magnitude: This is a synonym for length.
-  @ivar wrapped: Whether or not this item is wrapped data
   @note: Comparison operators can be done on Vector classes:
       - >, >=, <, <= test the vector magnitude
       - ==, != test vector values e.g. 1,2,3 != 1,2,4 even if they are the same length
@@ -106,11 +97,6 @@ class Euler:
   The Euler object
   ================
     This object gives access to Eulers in Blender.
-  @group Axises: x, y, z
-  @ivar x: The heading value in degrees.
-  @ivar y: The pitch value in degrees.
-  @ivar z: The roll value in degrees.
-  @ivar wrapped: Whether or not this object is wrapping data directly
   @note: You can access a euler object like a sequence
       - x = euler[0]
   @note: Comparison operators can be done:
@@ -152,16 +138,6 @@ class Quaternion:
   The Quaternion object
   =====================
     This object gives access to Quaternions in Blender.
-  @group Axises: x, y, z, w
-  @ivar w: The w value.
-  @ivar x: The x value.
-  @ivar y: The y value.
-  @ivar z: The z value.
-  @ivar wrapped: Wether or not this object wraps data directly
-  @ivar magnitude: The magnitude of the quaternion.
-  @ivar axis: Vector representing the axis of rotation.
-  @ivar angle: A scalar representing the amount of rotation
-  in degrees.
   @note: Comparison operators can be done:
       - ==, != test numeric values within epsilon
   @note: Math can be performed on Quaternion classes
@@ -215,10 +191,6 @@ class Matrix:
   """
   The Matrix Object
   =================
-    This object gives access to Matrices in Blender.
-  @ivar rowSize: The row size of the matrix.
-  @ivar colSize: The column size of the matrix.
-  @ivar wrapped: Whether or not this object wrapps internal data
   @note: Math can be performed on Matrix classes
       - mat + mat 
       - mat - mat 
diff --git a/source/blender/python/generic/Mathutils.c b/source/blender/python/generic/Mathutils.c
index 256965a2b87..fa2c60813ed 100644
--- a/source/blender/python/generic/Mathutils.c
+++ b/source/blender/python/generic/Mathutils.c
@@ -137,9 +137,9 @@ static char M_Mathutils_RotationMatrix_doc[] =
 "   :arg size: The size of the rotation matrix to construct [2, 4].\n"
 "   :type size: int\n"
 "   :arg axis: a string in ['X', 'Y', 'Z'] or a 3D Vector Object (optional when size is 2).\n"
-"   :type axis: string or vector\n"
+"   :type axis: string or :class:`Vector`\n"
 "   :return: A new rotation matrix.\n"
-"   :rtype: Matrix\n";
+"   :rtype: :class:`Matrix`\n";
 
 static PyObject *M_Mathutils_RotationMatrix(PyObject * self, PyObject * args)
 {
@@ -266,9 +266,9 @@ static char M_Mathutils_TranslationMatrix_doc[] =
 "   Create a matrix representing a translation.\n"
 "\n"
 "   :arg vector: The translation vector.\n"
-"   :type vector: Vector\n"
+"   :type vector: :class:`Vector`\n"
 "   :return: An identity matrix with a translation.\n"
-"   :rtype: Matrix\n";
+"   :rtype: :class:`Matrix`\n";
 
 static PyObject *M_Mathutils_TranslationMatrix(PyObject * self, VectorObject * vec)
 {
@@ -307,9 +307,9 @@ static char M_Mathutils_ScaleMatrix_doc[] =
 "   :arg size: The size of the scale matrix to construct [2, 4].\n"
 "   :type size: int\n"
 "   :arg axis: Direction to influence scale. (optional).\n"
-"   :type axis: Vector\n"
+"   :type axis: :class:`Vector`\n"
 "   :return: A new scale matrix.\n"
-"   :rtype: Matrix\n";
+"   :rtype: :class:`Matrix`\n";
 
 static PyObject *M_Mathutils_ScaleMatrix(PyObject * self, PyObject * args)
 {
@@ -397,10 +397,10 @@ static char M_Mathutils_OrthoProjectionMatrix_doc[] =
 "   :type plane: string\n"
 "   :arg size: The size of the projection matrix to construct [2, 4].\n"
 "   :type size: int\n"
-"   :arg axis: Arbitrary perpendicular plane vector.\n"
-"   :type axis: vector (optional)\n"
+"   :arg axis: Arbitrary perpendicular plane vector (optional).\n"
+"   :type axis: :class:`Vector`\n"
 "   :return: A new projection matrix.\n"
-"   :rtype: Matrix\n";
+"   :rtype: :class:`Matrix`\n";
 static PyObject *M_Mathutils_OrthoProjectionMatrix(PyObject * self, PyObject * args)
 {
 	VectorObject *vec = NULL;
@@ -502,7 +502,7 @@ static char M_Mathutils_ShearMatrix_doc[] =
 "   :arg size: The size of the shear matrix to construct [2, 4].\n"
 "   :type size: int\n"
 "   :return: A new shear matrix.\n"
-"   :rtype: Matrix\n";
+"   :rtype: :class:`Matrix`\n";
 
 static PyObject *M_Mathutils_ShearMatrix(PyObject * self, PyObject * args)
 {
@@ -661,6 +661,7 @@ int _BaseMathObject_WriteIndexCallback(BaseMathObject *self, int index)
 }
 
 /* BaseMathObject generic functions for all mathutils types */
+char BaseMathObject_Owner_doc[] = "The item this is wrapping or None  (readonly).";
 PyObject *BaseMathObject_getOwner( BaseMathObject * self, void *type )
 {
 	PyObject *ret= self->cb_user ? self->cb_user : Py_None;
@@ -668,6 +669,7 @@ PyObject *BaseMathObject_getOwner( BaseMathObject * self, void *type )
 	return ret;
 }
 
+char BaseMathObject_Wrapped_doc[] = "True when this object wraps external data (readonly). **type** boolean";
 PyObject *BaseMathObject_getWrapped( BaseMathObject *self, void *type )
 {
 	return PyBool_FromLong((self->wrapped == Py_WRAP) ? 1:0);
diff --git a/source/blender/python/generic/Mathutils.h b/source/blender/python/generic/Mathutils.h
index ad67d2e511e..fdf0b5d9ce4 100644
--- a/source/blender/python/generic/Mathutils.h
+++ b/source/blender/python/generic/Mathutils.h
@@ -41,6 +41,9 @@
 
 /* Can cast different mathutils types to this, use for generic funcs */
 
+extern char BaseMathObject_Wrapped_doc[];
+extern char BaseMathObject_Owner_doc[];
+
 typedef struct {
 	PyObject_VAR_HEAD
 	float *data;					/*array of data (alias), wrapped status depends on wrapped status */
diff --git a/source/blender/python/generic/euler.c b/source/blender/python/generic/euler.c
index b48c45b322f..82bd2ebe70a 100644
--- a/source/blender/python/generic/euler.c
+++ b/source/blender/python/generic/euler.c
@@ -92,7 +92,7 @@ static char Euler_ToQuat_doc[] =
 "   Return a quaternion representation of the euler.\n"
 "\n"
 "   :return: Quaternion representation of the euler.\n"
-"   :rtype: Quaternion\n";
+"   :rtype: :class:`Quaternion`\n";
 
 static PyObject *Euler_ToQuat(EulerObject * self)
 {
@@ -124,7 +124,7 @@ static char Euler_ToMatrix_doc[] =
 "   Return a matrix representation of the euler.\n"
 "\n"
 "   :return: A 3x3 roation matrix representation of the euler.\n"
-"   :rtype: Matrix\n";
+"   :rtype: :class:`Matrix`\n";
 
 static PyObject *Euler_ToMatrix(EulerObject * self)
 {
@@ -155,8 +155,9 @@ static char Euler_Unique_doc[] =
 ".. method:: unique()\n"
 "\n"
 "   Calculate a unique rotation for this euler. Avoids gimble lock.\n"
+"\n"
 "   :return: an instance of itself\n"
-"   :rtype: Euler\n";
+"   :rtype: :class:`Euler`\n";
 
 static PyObject *Euler_Unique(EulerObject * self)
 {
@@ -226,8 +227,9 @@ static char Euler_Zero_doc[] =
 ".. method:: zero()\n"
 "\n"
 "   Set all values to zero.\n"
+"\n"
 "   :return: an instance of itself\n"
-"   :rtype: Euler\n";
+"   :rtype: :class:`Euler`\n";
 
 static PyObject *Euler_Zero(EulerObject * self)
 {
@@ -293,9 +295,9 @@ static char Euler_MakeCompatible_doc[] =
 "   Make this euler compatible with another, so interpolating between them works as intended.\n"
 "\n"
 "   :arg other: make compatible with this rotation.\n"
-"   :type other: Euler\n"
+"   :type other: :class:`Euler`\n"
 "   :return: an instance of itself.\n"
-"   :rtype: Euler\n";
+"   :rtype: :class:`Euler`\n";
 
 static PyObject *Euler_MakeCompatible(EulerObject * self, EulerObject *value)
 {
@@ -343,7 +345,7 @@ static char Euler_copy_doc[] =
 "   Returns a copy of this euler.\n"
 "\n"
 "   :return: A copy of the euler.\n"
-"   :rtype: Euler\n"
+"   :rtype: :class:`Euler`\n"
 "\n"
 "   .. note:: use this to get a copy of a wrapped euler with no reference to the original data.\n";
 
@@ -551,7 +553,6 @@ static PySequenceMethods Euler_SeqMethods = {
 /*
  * vector axis, vector.x/y/z/w
  */
-	
 static PyObject *Euler_getAxis( EulerObject * self, void *type )
 {
 	return Euler_item(self, GET_INT_FROM_POINTER(type));
@@ -566,12 +567,12 @@ static int Euler_setAxis( EulerObject * self, PyObject * value, void * type )
 /* Python attributes get/set structure:                                      */
 /*****************************************************************************/
 static PyGetSetDef Euler_getseters[] = {
-	{"x", (getter)Euler_getAxis, (setter)Euler_setAxis, "Euler X axis", (void *)0},
-	{"y", (getter)Euler_getAxis, (setter)Euler_setAxis, "Euler Y axis", (void *)1},
-	{"z", (getter)Euler_getAxis, (setter)Euler_setAxis, "Euler Z axis", (void *)2},
+	{"x", (getter)Euler_getAxis, (setter)Euler_setAxis, "Euler X axis in radians. **type** float", (void *)0},
+	{"y", (getter)Euler_getAxis, (setter)Euler_setAxis, "Euler Y axis in radians. **type** float", (void *)1},
+	{"z", (getter)Euler_getAxis, (setter)Euler_setAxis, "Euler Z axis in radians. **type** float", (void *)2},
 
-	{"wrapped", (getter)BaseMathObject_getWrapped, (setter)NULL, "True when this wraps blenders internal data", NULL},
-	{"_owner", (getter)BaseMathObject_getOwner, (setter)NULL, "Read only owner for vectors that depend on another object", NULL},
+	{"wrapped", (getter)BaseMathObject_getWrapped, (setter)NULL, BaseMathObject_Wrapped_doc, NULL},
+	{"_owner", (getter)BaseMathObject_getOwner, (setter)NULL, BaseMathObject_Owner_doc, NULL},
 	{NULL,NULL,NULL,NULL,NULL}  /* Sentinel */
 };
 
@@ -590,6 +591,8 @@ static struct PyMethodDef Euler_methods[] = {
 };
 
 //------------------PY_OBECT DEFINITION--------------------------
+static char euler_doc[] = "This object gives access to Eulers in Blender.";
+
 PyTypeObject euler_Type = {
 	PyVarObject_HEAD_INIT(NULL, 0)
 	"euler",						//tp_name
@@ -611,7 +614,7 @@ PyTypeObject euler_Type = {
 	0,								//tp_setattro
 	0,								//tp_as_buffer
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, //tp_flags
-	0,								//tp_doc
+	euler_doc, //tp_doc
 	0,								//tp_traverse
 	0,								//tp_clear
 	(richcmpfunc)Euler_richcmpr,	//tp_richcompare
diff --git a/source/blender/python/generic/matrix.c b/source/blender/python/generic/matrix.c
index 00749002e59..a61cf4a2d41 100644
--- a/source/blender/python/generic/matrix.c
+++ b/source/blender/python/generic/matrix.c
@@ -206,7 +206,7 @@ static char Matrix_toQuat_doc[] =
 "   Return a quaternion representation of the rotation matrix.\n"
 "\n"
 "   :return: Quaternion representation of the rotation matrix.\n"
-"   :rtype: Quaternion\n";
+"   :rtype: :class:`Quaternion`\n";
 
 static PyObject *Matrix_toQuat(MatrixObject * self)
 {
@@ -235,9 +235,9 @@ static char Matrix_toEuler_doc[] =
 "   Return an Euler representation of the rotation matrix (3x3 or 4x4 matrix only).\n"
 "\n"
 "   :arg euler_compat: Optional euler argument the new euler will be made compatible with (no axis flipping between them). Useful for converting a series of matrices to animation curves.\n"
-"   :type euler_compat: Euler\n"
+"   :type euler_compat: :class:`Euler`\n"
 "   :return: Euler representation of the matrix.\n"
-"   :rtype: Euler\n";
+"   :rtype: :class:`Euler`\n";
 
 PyObject *Matrix_toEuler(MatrixObject * self, PyObject *args)
 {
@@ -294,8 +294,9 @@ static char Matrix_Resize4x4_doc[] =
 ".. method:: resize4x4()\n"
 "\n"
 "   Resize the matrix to 4x4.\n"
+"\n"
 "   :return: an instance of itself.\n"
-"   :rtype: Vector\n";
+"   :rtype: :class:`Vector`\n";
 
 PyObject *Matrix_Resize4x4(MatrixObject * self)
 {
@@ -358,8 +359,9 @@ static char Matrix_TranslationPart_doc[] =
 ".. method:: translation_part()\n"
 "\n"
 "   Return a the translation part of a 4 row matrix.\n"
+"\n"
 "   :return: Return a the translation of a matrix.\n"
-"   :rtype: Matrix\n"
+"   :rtype: :class:`Matrix`\n"
 "\n"
 "   .. note:: Note that the (4,4) element of a matrix can be used for uniform scaling too.\n";
 
@@ -386,8 +388,9 @@ static char Matrix_RotationPart_doc[] =
 ".. method:: rotation_part()\n"
 "\n"
 "   Return the 3d submatrix corresponding to the linear term of the embedded affine transformation in 3d. This matrix represents rotation and scale.\n"
+"\n"
 "   :return: Return the 3d matrix for rotation and scale.\n"
-"   :rtype: Matrix\n"
+"   :rtype: :class:`Matrix`\n"
 "\n"
 "   .. note:: Note that the (4,4) element of a matrix can be used for uniform scaling too.\n";
 
@@ -421,8 +424,9 @@ static char Matrix_scalePart_doc[] =
 ".. method:: scale_part()\n"
 "\n"
 "   Return a the scale part of a 3x3 or 4x4 matrix.\n"
+"\n"
 "   :return: Return a the scale of a matrix.\n"
-"   :rtype: Vector\n"
+"   :rtype: :class:`Vector`\n"
 "\n"
 "   .. note:: This method does not return negative a scale on any axis because it is not possible to obtain this data from the matrix alone.\n";
 
@@ -459,8 +463,9 @@ static char Matrix_Invert_doc[] =
 ".. method:: invert()\n"
 "\n"
 "   Set the matrix to its inverse.\n"
+"\n"
 "   :return: an instance of itself.\n"
-"   :rtype: Matrix\n"
+"   :rtype: :class:`Matrix`\n"
 "\n"
 "   .. note:: :exc:`ValueError` exception is raised.\n"
 "\n"
@@ -526,6 +531,7 @@ static char Matrix_Determinant_doc[] =
 ".. method:: determinant()\n"
 "\n"
 "   Return the determinant of a matrix.\n"
+"\n"
 "   :return: Return a the determinant of a matrix.\n"
 "   :rtype: float\n"
 "\n"
@@ -548,8 +554,9 @@ static char Matrix_Transpose_doc[] =
 ".. method:: transpose()\n"
 "\n"
 "   Set the matrix to its transpose.\n"
+"\n"
 "   :return: an instance of itself\n"
-"   :rtype: Matrix\n"
+"   :rtype: :class:`Matrix`\n"
 "\n"
 "   .. seealso:: <http://en.wikipedia.org/wiki/Transpose>\n";
 
@@ -586,8 +593,9 @@ static char Matrix_Zero_doc[] =
 ".. method:: zero()\n"
 "\n"
 "   Set all the matrix values to zero.\n"
+"\n"
 "   :return: an instance of itself\n"
-"   :rtype: Matrix\n";
+"   :rtype: :class:`Matrix`\n";
 
 PyObject *Matrix_Zero(MatrixObject * self)
 {
@@ -610,8 +618,9 @@ static char Matrix_Identity_doc[] =
 ".. method:: identity()\n"
 "\n"
 "   Set the matrix to the identity matrix.\n"
+"\n"
 "   :return: an instance of itself\n"
-"   :rtype: Matrix\n"
+"   :rtype: :class:`Matrix`\n"
 "\n"
 "   .. note:: An object with zero location and rotation, a scale of one, will have an identity matrix.\n"
 "\n"
@@ -650,8 +659,9 @@ static char Matrix_copy_doc[] =
 ".. method:: copy()\n"
 "\n"
 "   Returns a copy of this matrix.\n"
+"\n"
 "   :return: an instance of itself\n"
-"   :rtype: Matrix\n";
+"   :rtype: :class:`Matrix`\n";
 
 PyObject *Matrix_copy(MatrixObject * self)
 {
@@ -1225,12 +1235,11 @@ static PyObject *Matrix_getMedianScale( MatrixObject * self, void *type )
 /* Python attributes get/set structure:                                      */
 /*****************************************************************************/
 static PyGetSetDef Matrix_getseters[] = {
-	{"row_size", (getter)Matrix_getRowSize, (setter)NULL, "", NULL},
-	{"col_size", (getter)Matrix_getColSize, (setter)NULL, "", NULL},
-    {"median_scale", (getter)Matrix_getMedianScale, (setter)NULL, "", NULL},
-	{"wrapped", (getter)BaseMathObject_getWrapped, (setter)NULL, "", NULL},
-	{"_owner",(getter)BaseMathObject_getOwner, (setter)NULL, "",
-	 NULL},
+	{"row_size", (getter)Matrix_getRowSize, (setter)NULL, "The row size of the matrix (readonly). **type** int", NULL},
+	{"col_size", (getter)Matrix_getColSize, (setter)NULL, "The column size of the matrix (readonly). **type** int", NULL},
+    {"median_scale", (getter)Matrix_getMedianScale, (setter)NULL, "The average scale applied to each axis (readonly). **type** float", NULL},
+	{"wrapped", (getter)BaseMathObject_getWrapped, (setter)NULL, BaseMathObject_Wrapped_doc, NULL},
+	{"_owner",(getter)BaseMathObject_getOwner, (setter)NULL, BaseMathObject_Owner_doc, NULL},
 	{NULL,NULL,NULL,NULL,NULL}  /* Sentinel */
 };
 
@@ -1253,6 +1262,8 @@ static struct PyMethodDef Matrix_methods[] = {
 };
 
 /*------------------PY_OBECT DEFINITION--------------------------*/
+static char matrix_doc[] = "This object gives access to Matrices in Blender.";
+
 PyTypeObject matrix_Type = {
 	PyVarObject_HEAD_INIT(NULL, 0)
 	"matrix",						/*tp_name*/
@@ -1274,7 +1285,7 @@ PyTypeObject matrix_Type = {
 	0,								/*tp_setattro*/
 	0,								/*tp_as_buffer*/
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
-	0,								/*tp_doc*/
+	matrix_doc,						/*tp_doc*/
 	0,								/*tp_traverse*/
 	0,								/*tp_clear*/
 	(richcmpfunc)Matrix_richcmpr,	/*tp_richcompare*/
diff --git a/source/blender/python/generic/quat.c b/source/blender/python/generic/quat.c
index 7facc350625..9b5016b91d7 100644
--- a/source/blender/python/generic/quat.c
+++ b/source/blender/python/generic/quat.c
@@ -39,9 +39,9 @@ static char Quaternion_ToEuler_doc[] =
 "   Return Euler representation of the quaternion.\n"
 "\n"
 "   :arg euler_compat: Optional euler argument the new euler will be made compatible with (no axis flipping between them). Useful for converting a series of matrices to animation curves.\n"
-"   :type euler_compat: Euler\n"
+"   :type euler_compat: :class:`Euler`\n"
 "   :return: Euler representation of the quaternion.\n"
-"   :rtype: Euler\n";
+"   :rtype: :class:`Euler`\n";
 
 static PyObject *Quaternion_ToEuler(QuaternionObject * self, PyObject *args)
 {
@@ -98,7 +98,7 @@ static char Quaternion_ToMatrix_doc[] =
 "   Return a matrix representation of the quaternion.\n"
 "\n"
 "   :return: A 3x3 rotation matrix representation of the quaternion.\n"
-"   :rtype: Matrix\n";
+"   :rtype: :class:`Matrix`\n";
 
 static PyObject *Quaternion_ToMatrix(QuaternionObject * self)
 {
@@ -118,9 +118,9 @@ static char Quaternion_Cross_doc[] =
 "   Return the cross product of this quaternion and another.\n"
 "\n"
 "   :arg other: The other quaternion to perform the cross product with.\n"
-"   :type other: Quaternion\n"
+"   :type other: :class:`Quaternion`\n"
 "   :return: The cross product.\n"
-"   :rtype: Quaternion\n";
+"   :rtype: :class:`Quaternion`\n";
 
 static PyObject *Quaternion_Cross(QuaternionObject * self, QuaternionObject * value)
 {
@@ -145,9 +145,9 @@ static char Quaternion_Dot_doc[] =
 "   Return the dot product of this quaternion and another.\n"
 "\n"
 "   :arg other: The other quaternion to perform the dot product with.\n"
-"   :type other: Quaternion\n"
+"   :type other: :class:`Quaternion`\n"
 "   :return: The dot product.\n"
-"   :rtype: Quaternion\n";
+"   :rtype: :class:`Quaternion`\n";
 
 static PyObject *Quaternion_Dot(QuaternionObject * self, QuaternionObject * value)
 {
@@ -168,9 +168,9 @@ static char Quaternion_Difference_doc[] =
 "   Returns a quaternion representing the rotational difference.\n"
 "\n"
 "   :arg other: second quaternion.\n"
-"   :type other: Quaternion\n"
+"   :type other: :class:`Quaternion`\n"
 "   :return: the rotational difference between the two quat rotations.\n"
-"   :rtype: Quaternion\n";
+"   :rtype: :class:`Quaternion`\n";
 
 static PyObject *Quaternion_Difference(QuaternionObject * self, QuaternionObject * value)
 {
@@ -207,11 +207,11 @@ static char Quaternion_Slerp_doc[] =
 "   Returns the interpolation of two quaternions.\n"
 "\n"
 "   :arg other: value to interpolate with.\n"
-"   :type other: Quaternion\n"
+"   :type other: :class:`Quaternion`\n"
 "   :arg factor: The interpolation value in [0.0, 1.0].\n"
 "   :type factor: float\n"
 "   :return: The interpolated rotation.\n"
-"   :rtype: Quaternion\n";
+"   :rtype: :class:`Quaternion`\n";
 
 static PyObject *Quaternion_Slerp(QuaternionObject *self, PyObject *args)
 {
@@ -244,7 +244,7 @@ static char Quaternion_Normalize_doc[] =
 "   Normalize the quaternion.\n"
 "\n"
 "   :return: an instance of itself.\n"
-"   :rtype: Quaternion\n";
+"   :rtype: :class:`Quaternion`\n";
 
 static PyObject *Quaternion_Normalize(QuaternionObject * self)
 {
@@ -264,7 +264,7 @@ static char Quaternion_Inverse_doc[] =
 "   Set the quaternion to its inverse.\n"
 "\n"
 "   :return: an instance of itself.\n"
-"   :rtype: Quaternion\n";
+"   :rtype: :class:`Quaternion`\n";
 
 static PyObject *Quaternion_Inverse(QuaternionObject * self)
 {
@@ -284,7 +284,7 @@ static char Quaternion_Identity_doc[] =
 "   Set the quaternion to an identity quaternion.\n"
 "\n"
 "   :return: an instance of itself.\n"
-"   :rtype: Quaternion\n";
+"   :rtype: :class:`Quaternion`\n";
 
 static PyObject *Quaternion_Identity(QuaternionObject * self)
 {
@@ -304,7 +304,7 @@ static char Quaternion_Negate_doc[] =
 "   Set the quaternion to its negative.\n"
 "\n"
 "   :return: an instance of itself.\n"
-"   :rtype: Quaternion\n";
+"   :rtype: :class:`Quaternion`\n";
 
 static PyObject *Quaternion_Negate(QuaternionObject * self)
 {
@@ -324,7 +324,7 @@ static char Quaternion_Conjugate_doc[] =
 "   Set the quaternion to its conjugate (negate x, y, z).\n"
 "\n"
 "   :return: an instance of itself.\n"
-"   :rtype: Quaternion\n";
+"   :rtype: :class:`Quaternion`\n";
 
 static PyObject *Quaternion_Conjugate(QuaternionObject * self)
 {
@@ -344,7 +344,7 @@ static char Quaternion_copy_doc[] =
 "   Returns a copy of this quaternion.\n"
 "\n"
 "   :return: A copy of the quaternion.\n"
-"   :rtype: Quaternion\n"
+"   :rtype: :class:`Quaternion`\n"
 "\n"
 "   .. note:: use this to get a copy of a wrapped quaternion with no reference to the original data.\n";
 
@@ -847,19 +847,21 @@ static struct PyMethodDef Quaternion_methods[] = {
 /* Python attributes get/set structure:                                      */
 /*****************************************************************************/
 static PyGetSetDef Quaternion_getseters[] = {
-	{"w", (getter)Quaternion_getAxis, (setter)Quaternion_setAxis, "Quaternion W value", (void *)0},
-	{"x", (getter)Quaternion_getAxis, (setter)Quaternion_setAxis, "Quaternion X axis", (void *)1},
-	{"y", (getter)Quaternion_getAxis, (setter)Quaternion_setAxis, "Quaternion Y axis", (void *)2},
-	{"z", (getter)Quaternion_getAxis, (setter)Quaternion_setAxis, "Quaternion Z axis", (void *)3},
-	{"magnitude", (getter)Quaternion_getMagnitude, (setter)NULL, "Size of the quaternion", NULL},
-	{"angle", (getter)Quaternion_getAngle, (setter)NULL, "angle of the quaternion", NULL},
-	{"axis",(getter)Quaternion_getAxisVec, (setter)NULL, "quaternion axis as a vector", NULL},
-	{"wrapped", (getter)BaseMathObject_getWrapped, (setter)NULL, "True when this wraps blenders internal data", NULL},
-	{"_owner", (getter)BaseMathObject_getOwner, (setter)NULL, "Read only owner for vectors that depend on another object", NULL},
+	{"w", (getter)Quaternion_getAxis, (setter)Quaternion_setAxis, "Quaternion W value. **type** float", (void *)0},
+	{"x", (getter)Quaternion_getAxis, (setter)Quaternion_setAxis, "Quaternion X axis. **type** float", (void *)1},
+	{"y", (getter)Quaternion_getAxis, (setter)Quaternion_setAxis, "Quaternion Y axis. **type** float", (void *)2},
+	{"z", (getter)Quaternion_getAxis, (setter)Quaternion_setAxis, "Quaternion Z axis. **type** float", (void *)3},
+	{"magnitude", (getter)Quaternion_getMagnitude, (setter)NULL, "Size of the quaternion (readonly). **type** float", NULL},
+	{"angle", (getter)Quaternion_getAngle, (setter)NULL, "angle of the quaternion (readonly). **type** float", NULL},
+	{"axis",(getter)Quaternion_getAxisVec, (setter)NULL, "quaternion axis as a vector (readonly). **type** :class:`Vector`", NULL},
+	{"wrapped", (getter)BaseMathObject_getWrapped, (setter)NULL, BaseMathObject_Wrapped_doc, NULL},
+	{"_owner", (getter)BaseMathObject_getOwner, (setter)NULL, BaseMathObject_Owner_doc, NULL},
 	{NULL,NULL,NULL,NULL,NULL}  /* Sentinel */
 };
 
 //------------------PY_OBECT DEFINITION--------------------------
+static char quaternion_doc[] = "This object gives access to Quaternions in Blender.";
+
 PyTypeObject quaternion_Type = {
 	PyVarObject_HEAD_INIT(NULL, 0)
 	"quaternion",						//tp_name
@@ -881,7 +883,7 @@ PyTypeObject quaternion_Type = {
 	0,								//tp_setattro
 	0,								//tp_as_buffer
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, //tp_flags
-	0,								//tp_doc
+	quaternion_doc, //tp_doc
 	0,								//tp_traverse
 	0,								//tp_clear
 	(richcmpfunc)Quaternion_richcmpr,	//tp_richcompare
diff --git a/source/blender/python/generic/vector.c b/source/blender/python/generic/vector.c
index aa5b518ffab..784ea1a153f 100644
--- a/source/blender/python/generic/vector.c
+++ b/source/blender/python/generic/vector.c
@@ -97,8 +97,9 @@ static char Vector_Zero_doc[] =
 ".. method:: zero()\n"
 "\n"
 "   Set all values to zero.\n"
+"\n"
 "   :return: an instance of itself\n"
-"   :rtype: vector\n";
+"   :rtype: :class:`Vector`\n";
 
 static PyObject *Vector_Zero(VectorObject * self)
 {
@@ -116,8 +117,9 @@ static char Vector_Normalize_doc[] =
 ".. method:: normalize()\n"
 "\n"
 "   Normalize the vector, making the length of the vector always 1.0.\n"
+"\n"
 "   :return: an instance of itself\n"
-"   :rtype: vector\n"
+"   :rtype: :class:`Vector`\n"
 "\n"
 "   .. warning:: Normalizing a vector where all values are zero results in all axis having a nan value (not a number).\n"
 "\n"
@@ -150,8 +152,9 @@ static char Vector_Resize2D_doc[] =
 ".. method:: resize2D()\n"
 "\n"
 "   Resize the vector to 2D  (x, y).\n"
+"\n"
 "   :return: an instance of itself\n"
-"   :rtype: vector\n";
+"   :rtype: :class:`Vector`\n";
 
 static PyObject *Vector_Resize2D(VectorObject * self)
 {
@@ -179,8 +182,9 @@ static char Vector_Resize3D_doc[] =
 ".. method:: resize3D()\n"
 "\n"
 "   Resize the vector to 3D  (x, y, z).\n"
+"\n"
 "   :return: an instance of itself\n"
-"   :rtype: vector\n";
+"   :rtype: :class:`Vector`\n";
 
 static PyObject *Vector_Resize3D(VectorObject * self)
 {
@@ -211,8 +215,9 @@ static char Vector_Resize4D_doc[] =
 ".. method:: resize4D()\n"
 "\n"
 "   Resize the vector to 4D (x, y, z, w).\n"
+"\n"
 "   :return: an instance of itself\n"
-"   :rtype: vector\n";
+"   :rtype: :class:`Vector`\n";
 
 static PyObject *Vector_Resize4D(VectorObject * self)
 {
@@ -287,7 +292,7 @@ static char Vector_ToTrackQuat_doc[] =
 "   :arg up: Up axis in ['X', 'Y', 'Z'].\n"
 "   :type up: string\n"
 "   :return: rotation from the vector and the track and up axis."
-"   :rtype: Quaternion\n";
+"   :rtype: :class:`Quaternion`\n";
 
 static PyObject *Vector_ToTrackQuat( VectorObject * self, PyObject * args )
 {
@@ -404,9 +409,9 @@ static char Vector_Reflect_doc[] =
 "   Return the reflection vector from the *mirror* argument.\n"
 "\n"
 "   :arg mirror: This vector could be a normal from the reflecting surface.\n"
-"   :type mirror: vector\n"
-"   :return: The reflected vector.\n"
-"   :rtype: Vector object matching the size of this vector.\n";
+"   :type mirror: :class:`Vector`\n"
+"   :return: The reflected vector matching the size of this vector.\n"
+"   :rtype: :class:`Vector`\n";
 
 static PyObject *Vector_Reflect( VectorObject * self, VectorObject * value )
 {
@@ -443,9 +448,9 @@ static char Vector_Cross_doc[] =
 "   Return the cross product of this vector and another.\n"
 "\n"
 "   :arg other: The other vector to perform the cross product with.\n"
-"   :type other: vector\n"
+"   :type other: :class:`Vector`\n"
 "   :return: The cross product.\n"
-"   :rtype: Vector\n"
+"   :rtype: :class:`Vector`\n"
 "\n"
 "   .. note:: both vectors must be 3D\n";
 
@@ -477,9 +482,9 @@ static char Vector_Dot_doc[] =
 "   Return the dot product of this vector and another.\n"
 "\n"
 "   :arg other: The other vector to perform the dot product with.\n"
-"   :type other: vector\n"
+"   :type other: :class:`Vector`\n"
 "   :return: The dot product.\n"
-"   :rtype: Vector\n";
+"   :rtype: :class:`Vector`\n";
 
 static PyObject *Vector_Dot( VectorObject * self, VectorObject * value )
 {
@@ -510,7 +515,7 @@ static char Vector_Angle_doc[] =
 "\n"
 "   Return the angle between two vectors.\n"
 "\n"
-"   :type other: vector\n"
+"   :type other: :class:`Vector`\n"
 "   :return angle: angle in radians\n"
 "   :rtype: float\n"
 "\n"
@@ -566,13 +571,15 @@ static char Vector_Difference_doc[] =
 "   Returns a quaternion representing the rotational difference between this vector and another.\n"
 "\n"
 "   :arg other: second vector.\n"
-"   :type other: Vector\n"
+"   :type other: :class:`Vector`\n"
 "   :return: the rotational difference between the two vectors.\n"
-"   :rtype: Quaternion\n";
+"   :rtype: :class:`Quaternion`\n"
+"\n"
+"   .. note:: 2D vectors raise an :exc:`AttributeError`.\n";;
 
 static PyObject *Vector_Difference( VectorObject * self, VectorObject * value )
 {
-	float quat[4];
+	float quat[4], vec_a[3], vec_b[3];
 
 	if (!VectorObject_Check(value)) {
 		PyErr_SetString( PyExc_TypeError, "vec.difference(value): expected a vector argument" );
@@ -587,7 +594,10 @@ static PyObject *Vector_Difference( VectorObject * self, VectorObject * value )
 	if(!BaseMath_ReadCallback(self) || !BaseMath_ReadCallback(value))
 		return NULL;
 
-	rotation_between_vecs_to_quat(quat, self->vec, value->vec);
+	normalize_v3_v3(vec_a, self->vec);
+	normalize_v3_v3(vec_b, value->vec);
+
+	rotation_between_vecs_to_quat(quat, vec_a, vec_b);
 
 	return newQuaternionObject(quat, Py_NEW, NULL);
 }
@@ -597,9 +607,9 @@ static char Vector_Project_doc[] =
 "\n"
 "   Return the projection of this vector onto the *other*.\n"
 "\n"
-"   :type other: vector\n"
+"   :type other: :class:`Vector`\n"
 "   :return projection: the parallel projection vector\n"
-"   :rtype: vector\n";
+"   :rtype: :class:`Vector`\n";
 
 static PyObject *Vector_Project(VectorObject * self, VectorObject * value)
 {
@@ -644,11 +654,11 @@ static char Vector_Lerp_doc[] =
 "   Returns the interpolation of two vectors.\n"
 "\n"
 "   :arg other: value to interpolate with.\n"
-"   :type other: Vector\n"
+"   :type other: :class:`Vector`\n"
 "   :arg factor: The interpolation value in [0.0, 1.0].\n"
 "   :type factor: float\n"
 "   :return: The interpolated rotation.\n"
-"   :rtype: Vector\n";
+"   :rtype: :class:`Vector`\n";
 
 static PyObject *Vector_Lerp(VectorObject * self, PyObject * args)
 {
@@ -683,7 +693,7 @@ static char Vector_copy_doc[] =
 "   Returns a copy of this vector.\n"
 "\n"
 "   :return: A copy of the vector.\n"
-"   :rtype: Vector\n"
+"   :rtype: :class:`Vector`\n"
 "\n"
 "   .. note:: use this to get a copy of a wrapped vector with no reference to the original data.\n";
 
@@ -1619,38 +1629,14 @@ static int Vector_setSwizzle(VectorObject * self, PyObject * value, void *closur
 /* Python attributes get/set structure:                                      */
 /*****************************************************************************/
 static PyGetSetDef Vector_getseters[] = {
-	{"x",
-	 (getter)Vector_getAxis, (setter)Vector_setAxis,
-	 "Vector X axis",
-	 (void *)0},
-	{"y",
-	 (getter)Vector_getAxis, (setter)Vector_setAxis,
-	 "Vector Y axis",
-	 (void *)1},
-	{"z",
-	 (getter)Vector_getAxis, (setter)Vector_setAxis,
-	 "Vector Z axis",
-	 (void *)2},
-	{"w",
-	 (getter)Vector_getAxis, (setter)Vector_setAxis,
-	 "Vector Z axis",
-	 (void *)3},
-	{"length",
-	 (getter)Vector_getLength, (setter)Vector_setLength,
-	 "Vector Length",
-	 NULL},
-	{"magnitude",
-	 (getter)Vector_getLength, (setter)Vector_setLength,
-	 "Vector Length",
-	 NULL},
-	{"wrapped",
-	 (getter)BaseMathObject_getWrapped, (setter)NULL,
-	 "True when this wraps blenders internal data",
-	 NULL},
-	{"_owner",
-	 (getter)BaseMathObject_getOwner, (setter)NULL,
-	 "Read only owner for vectors that depend on another object",
-	 NULL},
+	{"x", (getter)Vector_getAxis, (setter)Vector_setAxis, "Vector X axis. **type** float", (void *)0},
+	{"y", (getter)Vector_getAxis, (setter)Vector_setAxis, "Vector Y axis. **type** float", (void *)1},
+	{"z", (getter)Vector_getAxis, (setter)Vector_setAxis, "Vector Z axis (3D Vectors only). **type** float", (void *)2},
+	{"w", (getter)Vector_getAxis, (setter)Vector_setAxis, "Vector W axis (4D Vectors only). **type** float", (void *)3},
+	{"length", (getter)Vector_getLength, (setter)Vector_setLength, "Vector Length. **type** float", NULL},
+	{"magnitude", (getter)Vector_getLength, (setter)Vector_setLength, "Vector Length. **type** float", NULL},
+	{"wrapped", (getter)BaseMathObject_getWrapped, (setter)NULL, BaseMathObject_Wrapped_doc, NULL},
+	{"_owner", (getter)BaseMathObject_getOwner, (setter)NULL, BaseMathObject_Owner_doc, NULL},
 	
 	/* autogenerated swizzle attrs, see python script below */
 	{"xx",   (getter)Vector_getSwizzle, (setter)Vector_setSwizzle, NULL, SET_INT_IN_POINTER(((0|SWIZZLE_VALID_AXIS) | ((0|SWIZZLE_VALID_AXIS)<<SWIZZLE_BITS_PER_AXIS)))}, /* 36 */
@@ -2077,8 +2063,9 @@ static char Vector_Negate_doc[] =
 ".. method:: negate()\n"
 "\n"
 "   Set all values to their negative.\n"
+"\n"
 "   :return: an instance of itself\n"
-"   :rtype: vector\n";
+"   :rtype: :class:`Vector`\n";
 
 static PyObject *Vector_Negate(VectorObject * self)
 {
diff --git a/source/blender/python/sphinx_doc_gen.py b/source/blender/python/sphinx_doc_gen.py
index 6ff845a794e..b5a5171d6a1 100644
--- a/source/blender/python/sphinx_doc_gen.py
+++ b/source/blender/python/sphinx_doc_gen.py
@@ -130,8 +130,7 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
     filepath = os.path.join(BASEPATH, module_name + ".rst")
     
     file = open(filepath, "w")
-    print(filepath)
-    print(filepath)
+
     fw = file.write
     
     fw(title + "\n")
@@ -169,18 +168,29 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
         if value.__doc__:
             for l in value.__doc__.split("\n"):
                 fw("   %s\n" % l)
-        fw("\n")
+            fw("\n")
 
-        for key, descr in value.__dict__.items():
+        for key in sorted(value.__dict__.keys()):
             if key.startswith("__"):
                 continue
+            descr = value.__dict__[key]
+            if type(descr) == GetSetDescriptorType:
+                if descr.__doc__:
+                    fw("   .. attribute:: %s\n\n" % key)
+                    for l in descr.__doc__.split("\n"):
+                        fw("   %s\n" % l)
+                    fw("\n")
 
-            descr_type = type(descr)
-            if descr_type in (MethodDescriptorType, ): # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
+        for key in sorted(value.__dict__.keys()):
+            if key.startswith("__"):
+                continue
+            descr = value.__dict__[key]
+            if type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
                 if descr.__doc__:
                     for l in descr.__doc__.split("\n"):
                         fw("   %s\n" % l)
                     fw("\n")
+            
         fw("\n\n")
 
     file.close()
@@ -215,8 +225,8 @@ def rna2sphinx(BASEPATH):
     fw("\n")
     fw(".. toctree::\n")
     fw("   :glob:\n\n")
-    #fw("   bpy.ops.*\n\n")
-    #fw("   bpy.types.*\n\n")
+    fw("   bpy.ops.*\n\n")
+    fw("   bpy.types.*\n\n")
     
     # py modules
     fw("   bpy.utils\n\n")
@@ -239,7 +249,7 @@ def rna2sphinx(BASEPATH):
     pymodule2sphinx(BASEPATH, "bpy.props", module, "Blender Python Property Definitions")
     
     import Mathutils as module
-    pymodule2sphinx(BASEPATH, "Mathutils", module, "Module Mathutils")
+    pymodule2sphinx(BASEPATH, "Mathutils", module, "Blender Mathutils")
     del module