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.

5 files changed, 124 insertions, 73 deletions

diff --git a/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_FalseBP1D.cpp b/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_FalseBP1D.cpp
index feef632992c..78566d915d6 100644
--- a/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_FalseBP1D.cpp
+++ b/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_FalseBP1D.cpp
@@ -6,8 +6,27 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for FalseBP1D instance  -----------*/
-static int FalseBP1D___init__(BPy_FalseBP1D* self, PyObject *args);
+//------------------------INSTANCE METHODS ----------------------------------
+
+static char FalseBP1D___doc__[] =
+".. method:: __call__(inter1, inter2)\n"
+"\n"
+"   Always returns false.\n"
+"\n"
+"   :arg inter1: The first Interface1D object.\n"
+"   :type inter1: :class:`Interface1D`\n"
+"   :arg inter2: The second Interface1D object.\n"
+"   :type inter2: :class:`Interface1D`\n"
+"   :return: False.\n"
+"   :rtype: bool\n";
+
+static int FalseBP1D___init__( BPy_FalseBP1D* self, PyObject *args )
+{
+	if(!( PyArg_ParseTuple(args, "") ))
+		return -1;
+	self->py_bp1D.bp1D = new Predicates1D::FalseBP1D();
+	return 0;
+}
 
 /*-----------------------BPy_FalseBP1D type definition ------------------------------*/
 PyTypeObject FalseBP1D_Type = {
@@ -31,7 +50,7 @@ PyTypeObject FalseBP1D_Type = {
 	0,                              /* tp_setattro */
 	0,                              /* tp_as_buffer */
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"FalseBP1D objects",            /* tp_doc */
+	FalseBP1D___doc__,              /* tp_doc */
 	0,                              /* tp_traverse */
 	0,                              /* tp_clear */
 	0,                              /* tp_richcompare */
@@ -51,16 +70,6 @@ PyTypeObject FalseBP1D_Type = {
 	0,                              /* tp_new */
 };
 
-//------------------------INSTANCE METHODS ----------------------------------
-
-int FalseBP1D___init__( BPy_FalseBP1D* self, PyObject *args )
-{
-	if(!( PyArg_ParseTuple(args, "") ))
-		return -1;
-	self->py_bp1D.bp1D = new Predicates1D::FalseBP1D();
-	return 0;
-}
-
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus
diff --git a/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_Length2DBP1D.cpp b/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_Length2DBP1D.cpp
index 09677e33725..5249e2ba6b0 100644
--- a/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_Length2DBP1D.cpp
+++ b/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_Length2DBP1D.cpp
@@ -6,10 +6,31 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for Length2DBP1D instance  -----------*/
-static int Length2DBP1D___init__(BPy_Length2DBP1D* self, PyObject *args);
+//------------------------INSTANCE METHODS ----------------------------------
+
+static char Length2DBP1D___doc__[] =
+".. method:: __call__(inter1, inter2)\n"
+"\n"
+"   Returns true if the 2D length of inter1 is less than the 2D length\n"
+"   of inter2.\n"
+"\n"
+"   :arg inter1: The first Interface1D object.\n"
+"   :type inter1: :class:`Interface1D`\n"
+"   :arg inter2: The second Interface1D object.\n"
+"   :type inter2: :class:`Interface1D`\n"
+"   :return: True or false.\n"
+"   :rtype: bool\n";
+
+static int Length2DBP1D___init__( BPy_Length2DBP1D* self, PyObject *args )
+{
+	if(!( PyArg_ParseTuple(args, "") ))
+		return -1;
+	self->py_bp1D.bp1D = new Predicates1D::Length2DBP1D();
+	return 0;
+}
 
 /*-----------------------BPy_Length2DBP1D type definition ------------------------------*/
+
 PyTypeObject Length2DBP1D_Type = {
 	PyVarObject_HEAD_INIT(NULL, 0)
 	"Length2DBP1D",                 /* tp_name */
@@ -31,7 +52,7 @@ PyTypeObject Length2DBP1D_Type = {
 	0,                              /* tp_setattro */
 	0,                              /* tp_as_buffer */
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"Length2DBP1D objects",         /* tp_doc */
+	Length2DBP1D___doc__,           /* tp_doc */
 	0,                              /* tp_traverse */
 	0,                              /* tp_clear */
 	0,                              /* tp_richcompare */
@@ -51,16 +72,6 @@ PyTypeObject Length2DBP1D_Type = {
 	0,                              /* tp_new */
 };
 
-//------------------------INSTANCE METHODS ----------------------------------
-
-int Length2DBP1D___init__( BPy_Length2DBP1D* self, PyObject *args )
-{
-	if(!( PyArg_ParseTuple(args, "") ))
-		return -1;
-	self->py_bp1D.bp1D = new Predicates1D::Length2DBP1D();
-	return 0;
-}
-
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus
diff --git a/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_SameShapeIdBP1D.cpp b/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_SameShapeIdBP1D.cpp
index a8fa365a6fe..5255752ff71 100644
--- a/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_SameShapeIdBP1D.cpp
+++ b/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_SameShapeIdBP1D.cpp
@@ -6,10 +6,30 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for SameShapeIdBP1D instance  -----------*/
-static int SameShapeIdBP1D___init__(BPy_SameShapeIdBP1D* self, PyObject *args);
+//------------------------INSTANCE METHODS ----------------------------------
+
+static char SameShapeIdBP1D___doc__[] =
+".. method:: __call__(inter1, inter2)\n"
+"\n"
+"   Returns true if inter1 and inter2 belong to the same shape.\n"
+"\n"
+"   :arg inter1: The first Interface1D object.\n"
+"   :type inter1: :class:`Interface1D`\n"
+"   :arg inter2: The second Interface1D object.\n"
+"   :type inter2: :class:`Interface1D`\n"
+"   :return: True or false.\n"
+"   :rtype: bool\n";
+
+static int SameShapeIdBP1D___init__( BPy_SameShapeIdBP1D* self, PyObject *args )
+{
+	if(!( PyArg_ParseTuple(args, "") ))
+		return -1;
+	self->py_bp1D.bp1D = new Predicates1D::SameShapeIdBP1D();
+	return 0;
+}
 
 /*-----------------------BPy_SameShapeIdBP1D type definition ------------------------------*/
+
 PyTypeObject SameShapeIdBP1D_Type = {
 	PyVarObject_HEAD_INIT(NULL, 0)
 	"SameShapeIdBP1D",              /* tp_name */
@@ -31,7 +51,7 @@ PyTypeObject SameShapeIdBP1D_Type = {
 	0,                              /* tp_setattro */
 	0,                              /* tp_as_buffer */
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"SameShapeIdBP1D objects",      /* tp_doc */
+	SameShapeIdBP1D___doc__,        /* tp_doc */
 	0,                              /* tp_traverse */
 	0,                              /* tp_clear */
 	0,                              /* tp_richcompare */
@@ -51,16 +71,6 @@ PyTypeObject SameShapeIdBP1D_Type = {
 	0,                              /* tp_new */
 };
 
-//------------------------INSTANCE METHODS ----------------------------------
-
-int SameShapeIdBP1D___init__( BPy_SameShapeIdBP1D* self, PyObject *args )
-{
-	if(!( PyArg_ParseTuple(args, "") ))
-		return -1;
-	self->py_bp1D.bp1D = new Predicates1D::SameShapeIdBP1D();
-	return 0;
-}
-
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus
diff --git a/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_TrueBP1D.cpp b/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_TrueBP1D.cpp
index 1dd6231182f..6df906a31d5 100644
--- a/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_TrueBP1D.cpp
+++ b/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_TrueBP1D.cpp
@@ -6,10 +6,30 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for TrueBP1D instance  -----------*/
-static int TrueBP1D___init__( BPy_TrueBP1D* self, PyObject *args );
+//------------------------INSTANCE METHODS ----------------------------------
+
+static char TrueBP1D___doc__[] =
+".. method:: __call__(inter1, inter2)\n"
+"\n"
+"   Always returns true.\n"
+"\n"
+"   :arg inter1: The first Interface1D object.\n"
+"   :type inter1: :class:`Interface1D`\n"
+"   :arg inter2: The second Interface1D object.\n"
+"   :type inter2: :class:`Interface1D`\n"
+"   :return: True.\n"
+"   :rtype: bool\n";
+
+static int TrueBP1D___init__( BPy_TrueBP1D* self, PyObject *args )
+{
+	if(!( PyArg_ParseTuple(args, "") ))
+		return -1;
+	self->py_bp1D.bp1D = new Predicates1D::TrueBP1D();
+	return 0;
+}
 
 /*-----------------------BPy_TrueBP1D type definition ------------------------------*/
+
 PyTypeObject TrueBP1D_Type = {
 	PyVarObject_HEAD_INIT(NULL, 0)
 	"TrueBP1D",                     /* tp_name */
@@ -31,7 +51,7 @@ PyTypeObject TrueBP1D_Type = {
 	0,                              /* tp_setattro */
 	0,                              /* tp_as_buffer */
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"TrueBP1D objects",             /* tp_doc */
+	TrueBP1D___doc__,               /* tp_doc */
 	0,                              /* tp_traverse */
 	0,                              /* tp_clear */
 	0,                              /* tp_richcompare */
@@ -51,16 +71,6 @@ PyTypeObject TrueBP1D_Type = {
 	0,                              /* tp_new */
 };
 
-//------------------------INSTANCE METHODS ----------------------------------
-
-int TrueBP1D___init__( BPy_TrueBP1D* self, PyObject *args )
-{
-	if(!( PyArg_ParseTuple(args, "") ))
-		return -1;
-	self->py_bp1D.bp1D = new Predicates1D::TrueBP1D();
-	return 0;
-}
-
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus
diff --git a/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_ViewMapGradientNormBP1D.cpp b/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_ViewMapGradientNormBP1D.cpp
index 38333cc91cd..5f433ae3e22 100644
--- a/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_ViewMapGradientNormBP1D.cpp
+++ b/source/blender/freestyle/intern/python/BinaryPredicate1D/BPy_ViewMapGradientNormBP1D.cpp
@@ -9,10 +9,39 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for ViewMapGradientNormBP1D instance  -----------*/
-static int ViewMapGradientNormBP1D___init__(BPy_ViewMapGradientNormBP1D* self, PyObject *args );
+//------------------------INSTANCE METHODS ----------------------------------
+
+//ViewMapGradientNormBP1D(int level, IntegrationType iType=MEAN, float sampling=2.0) 
+
+static char ViewMapGradientNormBP1D___doc__[] =
+".. method:: __call__(inter1, inter2)\n"
+"\n"
+"   Returns true if the evaluation of the Gradient norm Function is\n"
+"   higher for inter1 than for inter2.\n"
+"\n"
+"   :arg inter1: The first Interface1D object.\n"
+"   :type inter1: :class:`Interface1D`\n"
+"   :arg inter2: The second Interface1D object.\n"
+"   :type inter2: :class:`Interface1D`\n"
+"   :return: True or false.\n"
+"   :rtype: bool\n";
+
+static int ViewMapGradientNormBP1D___init__( BPy_ViewMapGradientNormBP1D* self, PyObject *args )
+{
+	int i;
+	PyObject *obj;
+	float f = 2.0;
+
+	if(!( PyArg_ParseTuple(args, "i|O!f", &i, &IntegrationType_Type, &obj, &f) ))
+		return -1;
+	
+	IntegrationType t = ( obj ) ? IntegrationType_from_BPy_IntegrationType(obj) : MEAN;
+	self->py_bp1D.bp1D = new Predicates1D::ViewMapGradientNormBP1D(i,t,f);
+	return 0;
+}
 
 /*-----------------------BPy_ViewMapGradientNormBP1D type definition ------------------------------*/
+
 PyTypeObject ViewMapGradientNormBP1D_Type = {
 	PyVarObject_HEAD_INIT(NULL, 0)
 	"ViewMapGradientNormBP1D",      /* tp_name */
@@ -34,7 +63,7 @@ PyTypeObject ViewMapGradientNormBP1D_Type = {
 	0,                              /* tp_setattro */
 	0,                              /* tp_as_buffer */
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"ViewMapGradientNormBP1D objects", /* tp_doc */
+	ViewMapGradientNormBP1D___doc__, /* tp_doc */
 	0,                              /* tp_traverse */
 	0,                              /* tp_clear */
 	0,                              /* tp_richcompare */
@@ -54,24 +83,6 @@ PyTypeObject ViewMapGradientNormBP1D_Type = {
 	0,                              /* tp_new */
 };
 
-//------------------------INSTANCE METHODS ----------------------------------
-
-//ViewMapGradientNormBP1D(int level, IntegrationType iType=MEAN, float sampling=2.0) 
-
-int ViewMapGradientNormBP1D___init__( BPy_ViewMapGradientNormBP1D* self, PyObject *args )
-{
-	int i;
-	PyObject *obj;
-	float f = 2.0;
-
-	if(!( PyArg_ParseTuple(args, "i|O!f", &i, &IntegrationType_Type, &obj, &f) ))
-		return -1;
-	
-	IntegrationType t = ( obj ) ? IntegrationType_from_BPy_IntegrationType(obj) : MEAN;
-	self->py_bp1D.bp1D = new Predicates1D::ViewMapGradientNormBP1D(i,t,f);
-	return 0;
-}
-
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus