Major documentation updates. The original Freestyle API reference

(http://freestyle.sourceforge.net/doc/html/index.html) has been
incorporated into the Blender/Freestyle Python API implementation
in the form of Sphinx-based embedded docstrings.  Some C++-specific
descriptions of classes and functions were revised so that they are
suitable for Python programmers.  Missing docstrings were filled,
and sparse descriptions were extended.  By means of the new
documentation system for Blender, an up-to-date Freestyle Python
API reference will be part of the Blender 2.5 documentation.

1 files changed, 100 insertions, 61 deletions

diff --git a/source/blender/freestyle/intern/python/BPy_IntegrationType.cpp b/source/blender/freestyle/intern/python/BPy_IntegrationType.cpp
index e55dff0ae87..050f75a2668 100644
--- a/source/blender/freestyle/intern/python/BPy_IntegrationType.cpp
+++ b/source/blender/freestyle/intern/python/BPy_IntegrationType.cpp
@@ -12,7 +12,88 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-static PyObject * Integrator_integrate( PyObject *self, PyObject *args );
+//------------------------ MODULE FUNCTIONS ----------------------------------
+
+static char Integrator_integrate___doc__[] =
+".. function:: integrate(fun, it, it_end, integration_type)\n"
+"\n"
+"   Returns a single value from a set of values evaluated at each 0D\n"
+"   element of this 1D element.\n"
+"\n"
+"   :arg fun: The UnaryFunction0D used to compute a value at each\n"
+"      Interface0D.\n"
+"   :type fun: :class:`UnaryFunction0D`\n"
+"   :arg it: The Interface0DIterator used to iterate over the 0D\n"
+"      elements of this 1D element. The integration will occur over\n"
+"      the 0D elements starting from the one pointed by it.\n"
+"   :type it: :class:`Interface0DIterator`\n"
+"   :arg it_end: The Interface0DIterator pointing the end of the 0D\n"
+"      elements of the 1D element.\n"
+"   :type it_end: :class:`Interface0DIterator`\n"
+"   :arg integration_type: The integration method used to compute a\n"
+"      single value from a set of values.\n"
+"   :type integration_type: :class:`IntegrationType`\n"
+"   :return: The single value obtained for the 1D element.  The return\n"
+"      value type is float if fun is of the :class:`UnaryFunction0DDouble`\n"
+"      or :class:`UnaryFunction0DFloat` type, and int if fun is of the\n"
+"      :class:`UnaryFunction0DUnsigned` type.\n"
+"   :rtype: int or float\n";
+
+static PyObject * Integrator_integrate( PyObject *self, PyObject *args )
+{
+	PyObject *obj1, *obj4 = 0;
+	BPy_Interface0DIterator *obj2, *obj3;
+
+#if 1
+	if(!( PyArg_ParseTuple(args, "O!O!O!|O!", &UnaryFunction0D_Type, &obj1,
+		&Interface0DIterator_Type, &obj2, &Interface0DIterator_Type, &obj3,
+		&IntegrationType_Type, &obj4) ))
+		return NULL;
+#else
+	if(!( PyArg_ParseTuple(args, "OOO|O", &obj1, &obj2, &obj3, &obj4) ))
+		return NULL;
+	if(!BPy_UnaryFunction0D_Check(obj1)) {
+		PyErr_SetString(PyExc_TypeError, "argument 1 must be a UnaryFunction0D object");
+		return NULL;
+	}
+	if(!BPy_Interface0DIterator_Check(obj2)) {
+		PyErr_SetString(PyExc_TypeError, "argument 2 must be a Interface0DIterator object");
+		return NULL;
+	}
+	if(!BPy_Interface0DIterator_Check(obj3)) {
+		PyErr_SetString(PyExc_TypeError, "argument 3 must be a Interface0DIterator object");
+		return NULL;
+	}
+	if(obj4 && !BPy_IntegrationType_Check(obj4)) {
+		PyErr_SetString(PyExc_TypeError, "argument 4 must be a IntegrationType object");
+		return NULL;
+	}
+#endif
+
+	Interface0DIterator it(*(obj2->if0D_it)), it_end(*(obj3->if0D_it));
+	IntegrationType t = ( obj4 ) ? IntegrationType_from_BPy_IntegrationType( obj4 ) : MEAN;
+
+	if( BPy_UnaryFunction0DDouble_Check(obj1) ) {
+		UnaryFunction0D<double> *fun = ((BPy_UnaryFunction0DDouble *)obj1)->uf0D_double;
+		double res = integrate( *fun, it, it_end, t );
+		return PyFloat_FromDouble( res );
+
+	} else if( BPy_UnaryFunction0DFloat_Check(obj1) ) {
+		UnaryFunction0D<float> *fun = ((BPy_UnaryFunction0DFloat *)obj1)->uf0D_float;
+		float res = integrate( *fun, it, it_end, t );
+		return PyFloat_FromDouble( res );
+
+	} else if( BPy_UnaryFunction0DUnsigned_Check(obj1) ) {
+		UnaryFunction0D<unsigned int> *fun = ((BPy_UnaryFunction0DUnsigned *)obj1)->uf0D_unsigned;
+		unsigned int res = integrate( *fun, it, it_end, t );
+		return PyLong_FromLong( res );
+
+	} else {
+		string msg("unsupported function type: " + string(obj1->ob_type->tp_name));
+		PyErr_SetString(PyExc_TypeError, msg.c_str());
+		return NULL;
+	}
+}
 
 /*-----------------------Integrator module docstring---------------------------------------*/
 
@@ -21,7 +102,7 @@ static char module_docstring[] = "The Blender Freestyle.Integrator submodule\n\n
 /*-----------------------Integrator module functions definitions---------------------------*/
 
 static PyMethodDef module_functions[] = {
-  {"integrate", (PyCFunction)Integrator_integrate, METH_VARARGS, ""},
+  {"integrate", (PyCFunction) Integrator_integrate, METH_VARARGS, Integrator_integrate___doc__},
   {NULL, NULL, 0, NULL}
 };
 
@@ -37,6 +118,22 @@ static PyModuleDef module_definition = {
 
 /*-----------------------BPy_IntegrationType type definition ------------------------------*/
 
+static char IntegrationType___doc__[] =
+"Different integration methods that can be invoked to integrate into a\n"
+"single value the set of values obtained from each 0D element of an 1D\n"
+"element:\n"
+"\n"
+"* IntegrationType.MEAN: The value computed for the 1D element is the\n"
+"  mean of the values obtained for the 0D elements.\n"
+"* IntegrationType.MIN: The value computed for the 1D element is the\n"
+"  minimum of the values obtained for the 0D elements.\n"
+"* IntegrationType.MAX: The value computed for the 1D element is the\n"
+"  maximum of the values obtained for the 0D elements.\n"
+"* IntegrationType.FIRST: The value computed for the 1D element is the\n"
+"  first of the values obtained for the 0D elements.\n"
+"* IntegrationType.LAST: The value computed for the 1D element is the\n"
+"  last of the values obtained for the 0D elements.\n";
+
 PyTypeObject IntegrationType_Type = {
 	PyVarObject_HEAD_INIT(NULL, 0)
 	"IntegrationType",              /* tp_name */
@@ -58,7 +155,7 @@ PyTypeObject IntegrationType_Type = {
 	0,                              /* tp_setattro */
 	0,                              /* tp_as_buffer */
 	Py_TPFLAGS_DEFAULT,             /* tp_flags */
-	"IntegrationType objects",      /* tp_doc */
+	IntegrationType___doc__,        /* tp_doc */
 	0,                              /* tp_traverse */
 	0,                              /* tp_clear */
 	0,                              /* tp_richcompare */
@@ -143,64 +240,6 @@ int IntegrationType_Init( PyObject *module )
 	return 0;
 }
 
-//------------------------ MODULE FUNCTIONS ----------------------------------
-
-static PyObject * Integrator_integrate( PyObject *self, PyObject *args )
-{
-	PyObject *obj1, *obj4 = 0;
-	BPy_Interface0DIterator *obj2, *obj3;
-
-#if 1
-	if(!( PyArg_ParseTuple(args, "O!O!O!|O!", &UnaryFunction0D_Type, &obj1,
-		&Interface0DIterator_Type, &obj2, &Interface0DIterator_Type, &obj3,
-		&IntegrationType_Type, &obj4) ))
-		return NULL;
-#else
-	if(!( PyArg_ParseTuple(args, "OOO|O", &obj1, &obj2, &obj3, &obj4) ))
-		return NULL;
-	if(!BPy_UnaryFunction0D_Check(obj1)) {
-		PyErr_SetString(PyExc_TypeError, "argument 1 must be a UnaryFunction0D object");
-		return NULL;
-	}
-	if(!BPy_Interface0DIterator_Check(obj2)) {
-		PyErr_SetString(PyExc_TypeError, "argument 2 must be a Interface0DIterator object");
-		return NULL;
-	}
-	if(!BPy_Interface0DIterator_Check(obj3)) {
-		PyErr_SetString(PyExc_TypeError, "argument 3 must be a Interface0DIterator object");
-		return NULL;
-	}
-	if(obj4 && !BPy_IntegrationType_Check(obj4)) {
-		PyErr_SetString(PyExc_TypeError, "argument 4 must be a IntegrationType object");
-		return NULL;
-	}
-#endif
-
-	Interface0DIterator it(*(obj2->if0D_it)), it_end(*(obj3->if0D_it));
-	IntegrationType t = ( obj4 ) ? IntegrationType_from_BPy_IntegrationType( obj4 ) : MEAN;
-
-	if( BPy_UnaryFunction0DDouble_Check(obj1) ) {
-		UnaryFunction0D<double> *fun = ((BPy_UnaryFunction0DDouble *)obj1)->uf0D_double;
-		double res = integrate( *fun, it, it_end, t );
-		return PyFloat_FromDouble( res );
-
-	} else if( BPy_UnaryFunction0DFloat_Check(obj1) ) {
-		UnaryFunction0D<float> *fun = ((BPy_UnaryFunction0DFloat *)obj1)->uf0D_float;
-		float res = integrate( *fun, it, it_end, t );
-		return PyFloat_FromDouble( res );
-
-	} else if( BPy_UnaryFunction0DUnsigned_Check(obj1) ) {
-		UnaryFunction0D<unsigned int> *fun = ((BPy_UnaryFunction0DUnsigned *)obj1)->uf0D_unsigned;
-		unsigned int res = integrate( *fun, it, it_end, t );
-		return PyLong_FromLong( res );
-
-	} else {
-		string msg("unsupported function type: " + string(obj1->ob_type->tp_name));
-		PyErr_SetString(PyExc_TypeError, msg.c_str());
-		return NULL;
-	}
-}
-
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus