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.

6 files changed, 186 insertions, 94 deletions

diff --git a/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_GetCurvilinearAbscissaF0D.cpp b/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_GetCurvilinearAbscissaF0D.cpp
index 06af72a45fd..9dfcf776103 100644
--- a/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_GetCurvilinearAbscissaF0D.cpp
+++ b/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_GetCurvilinearAbscissaF0D.cpp
@@ -8,8 +8,32 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for GetCurvilinearAbscissaF0D instance  -----------*/
-static int GetCurvilinearAbscissaF0D___init__(BPy_GetCurvilinearAbscissaF0D* self, PyObject *args);
+//------------------------INSTANCE METHODS ----------------------------------
+
+static char GetCurvilinearAbscissaF0D___doc__[] =
+".. method:: __init__()\n"
+"\n"
+"   Builds a GetCurvilinearAbscissaF0D object.\n"
+"\n"
+".. method:: __call__(it)\n"
+"\n"
+"   Returns the curvilinear abscissa of the :class:`Interface0D`\n"
+"   pointed by the Interface0DIterator in the context of its 1D\n"
+"   element.\n"
+"\n"
+"   :arg it: An Interface0DIterator object.\n"
+"   :type it: :class:`Interface0DIterator`\n"
+"   :return: The curvilinear abscissa of the pointed Interface0D.\n"
+"   :rtype: float\n";
+
+static int GetCurvilinearAbscissaF0D___init__( BPy_GetCurvilinearAbscissaF0D* self, PyObject *args )
+{
+	if( !PyArg_ParseTuple(args, "") )
+		return -1;
+	self->py_uf0D_float.uf0D_float = new Functions0D::GetCurvilinearAbscissaF0D();
+	self->py_uf0D_float.uf0D_float->py_uf0D = (PyObject *)self;
+	return 0;
+}
 
 /*-----------------------BPy_GetCurvilinearAbscissaF0D type definition ------------------------------*/
 
@@ -34,7 +58,7 @@ PyTypeObject GetCurvilinearAbscissaF0D_Type = {
 	0,                              /* tp_setattro */
 	0,                              /* tp_as_buffer */
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"GetCurvilinearAbscissaF0D objects", /* tp_doc */
+	GetCurvilinearAbscissaF0D___doc__, /* tp_doc */
 	0,                              /* tp_traverse */
 	0,                              /* tp_clear */
 	0,                              /* tp_richcompare */
@@ -54,17 +78,6 @@ PyTypeObject GetCurvilinearAbscissaF0D_Type = {
 	0,                              /* tp_new */
 };
 
-//------------------------INSTANCE METHODS ----------------------------------
-
-int GetCurvilinearAbscissaF0D___init__( BPy_GetCurvilinearAbscissaF0D* self, PyObject *args )
-{
-	if( !PyArg_ParseTuple(args, "") )
-		return -1;
-	self->py_uf0D_float.uf0D_float = new Functions0D::GetCurvilinearAbscissaF0D();
-	self->py_uf0D_float.uf0D_float->py_uf0D = (PyObject *)self;
-	return 0;
-}
-
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus
diff --git a/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_GetParameterF0D.cpp b/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_GetParameterF0D.cpp
index f13d67e53d2..d8861ac2f77 100644
--- a/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_GetParameterF0D.cpp
+++ b/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_GetParameterF0D.cpp
@@ -8,8 +8,31 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for GetParameterF0D instance  -----------*/
-static int GetParameterF0D___init__(BPy_GetParameterF0D* self, PyObject *args);
+//------------------------INSTANCE METHODS ----------------------------------
+
+static char GetParameterF0D___doc__[] =
+".. method:: __init__()\n"
+"\n"
+"   Builds a GetParameterF0D object.\n"
+"\n"
+".. method:: __call__(it)\n"
+"\n"
+"   Returns the parameter of the :class:`Interface0D` pointed by the\n"
+"   Interface0DIterator in the context of its 1D element.\n"
+"\n"
+"   :arg it: An Interface0DIterator object.\n"
+"   :type it: :class:`Interface0DIterator`\n"
+"   :return: The parameter of an Interface0D.\n"
+"   :rtype: float\n";
+
+static int GetParameterF0D___init__( BPy_GetParameterF0D* self, PyObject *args )
+{
+	if( !PyArg_ParseTuple(args, "") )
+		return -1;
+	self->py_uf0D_float.uf0D_float = new Functions0D::GetParameterF0D();
+	self->py_uf0D_float.uf0D_float->py_uf0D = (PyObject *)self;
+	return 0;
+}
 
 /*-----------------------BPy_GetParameterF0D type definition ------------------------------*/
 
@@ -34,7 +57,7 @@ PyTypeObject GetParameterF0D_Type = {
 	0,                              /* tp_setattro */
 	0,                              /* tp_as_buffer */
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"GetParameterF0D objects",      /* tp_doc */
+	GetParameterF0D___doc__,        /* tp_doc */
 	0,                              /* tp_traverse */
 	0,                              /* tp_clear */
 	0,                              /* tp_richcompare */
@@ -54,17 +77,6 @@ PyTypeObject GetParameterF0D_Type = {
 	0,                              /* tp_new */
 };
 
-//------------------------INSTANCE METHODS ----------------------------------
-
-int GetParameterF0D___init__( BPy_GetParameterF0D* self, PyObject *args )
-{
-	if( !PyArg_ParseTuple(args, "") )
-		return -1;
-	self->py_uf0D_float.uf0D_float = new Functions0D::GetParameterF0D();
-	self->py_uf0D_float.uf0D_float->py_uf0D = (PyObject *)self;
-	return 0;
-}
-
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus
diff --git a/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_GetViewMapGradientNormF0D.cpp b/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_GetViewMapGradientNormF0D.cpp
index 68c159d077a..b753727fbf5 100644
--- a/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_GetViewMapGradientNormF0D.cpp
+++ b/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_GetViewMapGradientNormF0D.cpp
@@ -8,8 +8,38 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for GetViewMapGradientNormF0D instance  -----------*/
-static int GetViewMapGradientNormF0D___init__(BPy_GetViewMapGradientNormF0D* self, PyObject *args);
+//------------------------INSTANCE METHODS ----------------------------------
+
+static char GetViewMapGradientNormF0D___doc__[] =
+".. method:: __init__(level)\n"
+"\n"
+"   Builds a GetViewMapGradientNormF0D object.\n"
+"\n"
+"   :arg level: The level of the pyramid from which the pixel must be\n"
+"      read.\n"
+"   :type level: int\n"
+"\n"
+".. method:: __call__(it)\n"
+"\n"
+"   Returns the norm of the gradient of the global viewmap density\n"
+"   image.\n"
+"\n"
+"   :arg it: An Interface0DIterator object.\n"
+"   :type it: :class:`Interface0DIterator`\n"
+"   :return: The norm of the gradient of the global viewmap density\n"
+"      image.\n"
+"   :rtype: float\n";
+
+static int GetViewMapGradientNormF0D___init__( BPy_GetViewMapGradientNormF0D* self, PyObject *args)
+{
+	int i;
+
+	if( !PyArg_ParseTuple(args, "i", &i) )
+		return -1;
+	self->py_uf0D_float.uf0D_float = new Functions0D::GetViewMapGradientNormF0D(i);
+	self->py_uf0D_float.uf0D_float->py_uf0D = (PyObject *)self;
+	return 0;
+}
 
 /*-----------------------BPy_GetViewMapGradientNormF0D type definition ------------------------------*/
 
@@ -34,7 +64,7 @@ PyTypeObject GetViewMapGradientNormF0D_Type = {
 	0,                              /* tp_setattro */
 	0,                              /* tp_as_buffer */
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"GetViewMapGradientNormF0D objects", /* tp_doc */
+	GetViewMapGradientNormF0D___doc__, /* tp_doc */
 	0,                              /* tp_traverse */
 	0,                              /* tp_clear */
 	0,                              /* tp_richcompare */
@@ -54,19 +84,6 @@ PyTypeObject GetViewMapGradientNormF0D_Type = {
 	0,                              /* tp_new */
 };
 
-//------------------------INSTANCE METHODS ----------------------------------
-
-int GetViewMapGradientNormF0D___init__( BPy_GetViewMapGradientNormF0D* self, PyObject *args)
-{
-	int i;
-
-	if( !PyArg_ParseTuple(args, "i", &i) )
-		return -1;
-	self->py_uf0D_float.uf0D_float = new Functions0D::GetViewMapGradientNormF0D(i);
-	self->py_uf0D_float.uf0D_float->py_uf0D = (PyObject *)self;
-	return 0;
-}
-
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus
diff --git a/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_ReadCompleteViewMapPixelF0D.cpp b/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_ReadCompleteViewMapPixelF0D.cpp
index 619e59757f0..660f2b9f0c5 100644
--- a/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_ReadCompleteViewMapPixelF0D.cpp
+++ b/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_ReadCompleteViewMapPixelF0D.cpp
@@ -8,8 +8,36 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for ReadCompleteViewMapPixelF0D instance  -----------*/
-	static int ReadCompleteViewMapPixelF0D___init__(BPy_ReadCompleteViewMapPixelF0D* self, PyObject *args);
+//------------------------INSTANCE METHODS ----------------------------------
+
+static char ReadCompleteViewMapPixelF0D___doc__[] =
+".. method:: __init__(level)\n"
+"\n"
+"   Builds a ReadCompleteViewMapPixelF0D object.\n"
+"\n"
+"   :arg level: The level of the pyramid from which the pixel must be\n"
+"      read.\n"
+"   :type level: int\n"
+"\n"
+".. method:: __call__(it)\n"
+"\n"
+"   Reads a pixel in one of the level of the complete viewmap.\n"
+"\n"
+"   :arg it: An Interface0DIterator object.\n"
+"   :type it: :class:`Interface0DIterator`\n"
+"   :return: A pixel in one of the level of the complete viewmap.\n"
+"   :rtype: float\n";
+
+static int ReadCompleteViewMapPixelF0D___init__( BPy_ReadCompleteViewMapPixelF0D* self, PyObject *args)
+{
+	int i;
+
+	if( !PyArg_ParseTuple(args, "i", &i) )
+		return -1;
+	self->py_uf0D_float.uf0D_float = new Functions0D::ReadCompleteViewMapPixelF0D(i);
+	self->py_uf0D_float.uf0D_float->py_uf0D = (PyObject *)self;
+	return 0;
+}
 
 /*-----------------------BPy_ReadCompleteViewMapPixelF0D type definition ------------------------------*/
 
@@ -34,7 +62,7 @@ PyTypeObject ReadCompleteViewMapPixelF0D_Type = {
 	0,                              /* tp_setattro */
 	0,                              /* tp_as_buffer */
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"ReadCompleteViewMapPixelF0D objects", /* tp_doc */
+	ReadCompleteViewMapPixelF0D___doc__, /* tp_doc */
 	0,                              /* tp_traverse */
 	0,                              /* tp_clear */
 	0,                              /* tp_richcompare */
@@ -54,19 +82,6 @@ PyTypeObject ReadCompleteViewMapPixelF0D_Type = {
 	0,                              /* tp_new */
 };
 
-//------------------------INSTANCE METHODS ----------------------------------
-
-int ReadCompleteViewMapPixelF0D___init__( BPy_ReadCompleteViewMapPixelF0D* self, PyObject *args)
-{
-	int i;
-
-	if( !PyArg_ParseTuple(args, "i", &i) )
-		return -1;
-	self->py_uf0D_float.uf0D_float = new Functions0D::ReadCompleteViewMapPixelF0D(i);
-	self->py_uf0D_float.uf0D_float->py_uf0D = (PyObject *)self;
-	return 0;
-}
-
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus
diff --git a/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_ReadMapPixelF0D.cpp b/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_ReadMapPixelF0D.cpp
index b7e656ca842..6826bda4c09 100644
--- a/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_ReadMapPixelF0D.cpp
+++ b/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_ReadMapPixelF0D.cpp
@@ -8,8 +8,39 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for ReadMapPixelF0D instance  -----------*/
-static int ReadMapPixelF0D___init__(BPy_ReadMapPixelF0D* self, PyObject *args);
+//------------------------INSTANCE METHODS ----------------------------------
+
+static char ReadMapPixelF0D___doc__[] =
+".. method:: __init__(iMapName, level)\n"
+"\n"
+"   Builds a ReadMapPixelF0D object.\n"
+"\n"
+"   :arg iMapName: The name of the map to be read.\n"
+"   :type iMapName: string\n"
+"   :arg level: The level of the pyramid from which the pixel must be\n"
+"      read.\n"
+"   :type level: int\n"
+"\n"
+".. method:: __call__(it)\n"
+"\n"
+"   Reads a pixel in a map.\n"
+"\n"
+"   :arg it: An Interface0DIterator object.\n"
+"   :type it: :class:`Interface0DIterator`\n"
+"   :return: A pixel in a map.\n"
+"   :rtype: float\n";
+
+static int ReadMapPixelF0D___init__( BPy_ReadMapPixelF0D* self, PyObject *args)
+{
+	const char *s;
+	int i;
+
+	if( !PyArg_ParseTuple(args, "si", &s, &i) )
+		return -1;
+	self->py_uf0D_float.uf0D_float = new Functions0D::ReadMapPixelF0D(s,i);
+	self->py_uf0D_float.uf0D_float->py_uf0D = (PyObject *)self;
+	return 0;
+}
 
 /*-----------------------BPy_ReadMapPixelF0D type definition ------------------------------*/
 
@@ -34,7 +65,7 @@ PyTypeObject ReadMapPixelF0D_Type = {
 	0,                              /* tp_setattro */
 	0,                              /* tp_as_buffer */
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"ReadMapPixelF0D objects",      /* tp_doc */
+	ReadMapPixelF0D___doc__,        /* tp_doc */
 	0,                              /* tp_traverse */
 	0,                              /* tp_clear */
 	0,                              /* tp_richcompare */
@@ -54,20 +85,6 @@ PyTypeObject ReadMapPixelF0D_Type = {
 	0,                              /* tp_new */
 };
 
-//------------------------INSTANCE METHODS ----------------------------------
-
-int ReadMapPixelF0D___init__( BPy_ReadMapPixelF0D* self, PyObject *args)
-{
-	const char *s;
-	int i;
-
-	if( !PyArg_ParseTuple(args, "si", &s, &i) )
-		return -1;
-	self->py_uf0D_float.uf0D_float = new Functions0D::ReadMapPixelF0D(s,i);
-	self->py_uf0D_float.uf0D_float->py_uf0D = (PyObject *)self;
-	return 0;
-}
-
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus
diff --git a/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_ReadSteerableViewMapPixelF0D.cpp b/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_ReadSteerableViewMapPixelF0D.cpp
index bf6e004f2e3..5d551d9b910 100644
--- a/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_ReadSteerableViewMapPixelF0D.cpp
+++ b/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_float/BPy_ReadSteerableViewMapPixelF0D.cpp
@@ -8,8 +8,40 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for ReadSteerableViewMapPixelF0D instance  -----------*/
-static int ReadSteerableViewMapPixelF0D___init__(BPy_ReadSteerableViewMapPixelF0D* self, PyObject *args);
+//------------------------INSTANCE METHODS ----------------------------------
+
+static char ReadSteerableViewMapPixelF0D___doc__[] =
+".. method:: __init__(nOrientation, level)\n"
+"\n"
+"   Builds a ReadSteerableViewMapPixelF0D object.\n"
+"\n"
+"   :arg nOrientation: The integer belonging to [0, 4] indicating the\n"
+"      orientation (E, NE, N, NW) we are interested in.\n"
+"   :type nOrientation: int\n"
+"   :arg level: The level of the pyramid from which the pixel must be\n"
+"      read.\n"
+"   :type level: int\n"
+"\n"
+".. method:: __call__(it)\n"
+"\n"
+"   Reads a pixel in one of the level of one of the steerable viewmaps.\n"
+"\n"
+"   :arg it: An Interface0DIterator object.\n"
+"   :type it: :class:`Interface0DIterator`\n"
+"   :return: A pixel in one of the level of one of the steerable viewmaps.\n"
+"   :rtype: float\n";
+
+static int ReadSteerableViewMapPixelF0D___init__( BPy_ReadSteerableViewMapPixelF0D* self, PyObject *args)
+{
+	unsigned int u;
+	int i;
+
+	if( !PyArg_ParseTuple(args, "Ii", &u, &i) )
+		return -1;
+	self->py_uf0D_float.uf0D_float = new Functions0D::ReadSteerableViewMapPixelF0D(u,i);
+	self->py_uf0D_float.uf0D_float->py_uf0D = (PyObject *)self;
+	return 0;
+}
 
 /*-----------------------BPy_ReadSteerableViewMapPixelF0D type definition ------------------------------*/
 
@@ -34,7 +66,7 @@ PyTypeObject ReadSteerableViewMapPixelF0D_Type = {
 	0,                              /* tp_setattro */
 	0,                              /* tp_as_buffer */
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"ReadSteerableViewMapPixelF0D objects", /* tp_doc */
+	ReadSteerableViewMapPixelF0D___doc__, /* tp_doc */
 	0,                              /* tp_traverse */
 	0,                              /* tp_clear */
 	0,                              /* tp_richcompare */
@@ -54,20 +86,6 @@ PyTypeObject ReadSteerableViewMapPixelF0D_Type = {
 	0,                              /* tp_new */
 };
 
-//------------------------INSTANCE METHODS ----------------------------------
-
-int ReadSteerableViewMapPixelF0D___init__( BPy_ReadSteerableViewMapPixelF0D* self, PyObject *args)
-{
-	unsigned int u;
-	int i;
-
-	if( !PyArg_ParseTuple(args, "Ii", &u, &i) )
-		return -1;
-	self->py_uf0D_float.uf0D_float = new Functions0D::ReadSteerableViewMapPixelF0D(u,i);
-	self->py_uf0D_float.uf0D_float->py_uf0D = (PyObject *)self;
-	return 0;
-}
-
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus