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, 83 insertions, 62 deletions

diff --git a/source/blender/freestyle/intern/python/BPy_BinaryPredicate1D.cpp b/source/blender/freestyle/intern/python/BPy_BinaryPredicate1D.cpp
index 384aafeb567..30c63e73630 100644
--- a/source/blender/freestyle/intern/python/BPy_BinaryPredicate1D.cpp
+++ b/source/blender/freestyle/intern/python/BPy_BinaryPredicate1D.cpp
@@ -15,62 +15,6 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for BinaryPredicate1D instance  -----------*/
-static int BinaryPredicate1D___init__(BPy_BinaryPredicate1D *self, PyObject *args, PyObject *kwds);
-static void BinaryPredicate1D___dealloc__(BPy_BinaryPredicate1D *self);
-static PyObject * BinaryPredicate1D___repr__(BPy_BinaryPredicate1D *self);
-
-static PyObject * BinaryPredicate1D_getName( BPy_BinaryPredicate1D *self, PyObject *args);
-static PyObject * BinaryPredicate1D___call__( BPy_BinaryPredicate1D *self, PyObject *args, PyObject *kwds);
-
-/*----------------------BinaryPredicate1D instance definitions ----------------------------*/
-static PyMethodDef BPy_BinaryPredicate1D_methods[] = {
-	{"getName", ( PyCFunction ) BinaryPredicate1D_getName, METH_NOARGS, "() Returns the string of the name of the binary predicate."},
-	{NULL, NULL, 0, NULL}
-};
-
-/*-----------------------BPy_BinaryPredicate1D type definition ------------------------------*/
-PyTypeObject BinaryPredicate1D_Type = {
-	PyVarObject_HEAD_INIT(NULL, 0)
-	"BinaryPredicate1D",            /* tp_name */
-	sizeof(BPy_BinaryPredicate1D),  /* tp_basicsize */
-	0,                              /* tp_itemsize */
-	(destructor)BinaryPredicate1D___dealloc__, /* tp_dealloc */
-	0,                              /* tp_print */
-	0,                              /* tp_getattr */
-	0,                              /* tp_setattr */
-	0,                              /* tp_reserved */
-	(reprfunc)BinaryPredicate1D___repr__, /* tp_repr */
-	0,                              /* tp_as_number */
-	0,                              /* tp_as_sequence */
-	0,                              /* tp_as_mapping */
-	0,                              /* tp_hash  */
-	(ternaryfunc)BinaryPredicate1D___call__, /* tp_call */
-	0,                              /* tp_str */
-	0,                              /* tp_getattro */
-	0,                              /* tp_setattro */
-	0,                              /* tp_as_buffer */
-	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"BinaryPredicate1D objects",    /* tp_doc */
-	0,                              /* tp_traverse */
-	0,                              /* tp_clear */
-	0,                              /* tp_richcompare */
-	0,                              /* tp_weaklistoffset */
-	0,                              /* tp_iter */
-	0,                              /* tp_iternext */
-	BPy_BinaryPredicate1D_methods,  /* tp_methods */
-	0,                              /* tp_members */
-	0,                              /* tp_getset */
-	0,                              /* tp_base */
-	0,                              /* tp_dict */
-	0,                              /* tp_descr_get */
-	0,                              /* tp_descr_set */
-	0,                              /* tp_dictoffset */
-	(initproc)BinaryPredicate1D___init__, /* tp_init */
-	0,                              /* tp_alloc */
-	PyType_GenericNew,              /* tp_new */
-};
-
 //-------------------MODULE INITIALIZATION--------------------------------
 int BinaryPredicate1D_Init( PyObject *module )
 {
@@ -110,10 +54,32 @@ int BinaryPredicate1D_Init( PyObject *module )
 	return 0;
 }
 
-
 //------------------------INSTANCE METHODS ----------------------------------
 
-int BinaryPredicate1D___init__(BPy_BinaryPredicate1D *self, PyObject *args, PyObject *kwds)
+static char BinaryPredicate1D___doc__[] =
+"Base class for binary predicates working on :class:`Interface1D`\n"
+"objects.  A BinaryPredicate1D is typically an ordering relation\n"
+"between two Interface1D objects.  The predicate evaluates a relation\n"
+"between the two Interface1D instances and returns a boolean value (true\n"
+"or false).  It is used by invoking the __call__() method.\n"
+"\n"
+".. method:: __init__()\n"
+"\n"
+"   Default constructor.\n"
+"\n"
+".. method:: __call__(inter1, inter2)\n"
+"\n"
+"   Must be overload by inherited classes. It evaluates a relation\n"
+"   between two Interface1D objects.\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 BinaryPredicate1D___init__(BPy_BinaryPredicate1D *self, PyObject *args, PyObject *kwds)
 {
     if ( !PyArg_ParseTuple(args, "") )
         return -1;
@@ -122,24 +88,32 @@ int BinaryPredicate1D___init__(BPy_BinaryPredicate1D *self, PyObject *args, PyOb
 	return 0;
 }
 
-void BinaryPredicate1D___dealloc__(BPy_BinaryPredicate1D* self)
+static void BinaryPredicate1D___dealloc__(BPy_BinaryPredicate1D* self)
 {
 	if (self->bp1D)
 		delete self->bp1D;
     Py_TYPE(self)->tp_free((PyObject*)self);
 }
 
-PyObject * BinaryPredicate1D___repr__(BPy_BinaryPredicate1D* self)
+static PyObject * BinaryPredicate1D___repr__(BPy_BinaryPredicate1D* self)
 {
     return PyUnicode_FromFormat("type: %s - address: %p", self->bp1D->getName().c_str(), self->bp1D );
 }
 
-PyObject *BinaryPredicate1D_getName( BPy_BinaryPredicate1D *self, PyObject *args)
+static char BinaryPredicate1D_getName___doc__[] =
+".. method:: getName()\n"
+"\n"
+"   Returns the name of the binary 1D predicate.\n"
+"\n"
+"   :return: The name of the binary 1D predicate.\n"
+"   :rtype: string\n";
+
+static PyObject *BinaryPredicate1D_getName( BPy_BinaryPredicate1D *self, PyObject *args)
 {
 	return PyUnicode_FromFormat( self->bp1D->getName().c_str() );
 }
 
-PyObject *BinaryPredicate1D___call__( BPy_BinaryPredicate1D *self, PyObject *args, PyObject *kwds)
+static PyObject *BinaryPredicate1D___call__( BPy_BinaryPredicate1D *self, PyObject *args, PyObject *kwds)
 {
 	BPy_Interface1D *obj1, *obj2;
 	
@@ -164,6 +138,53 @@ PyObject *BinaryPredicate1D___call__( BPy_BinaryPredicate1D *self, PyObject *arg
 	return PyBool_from_bool( self->bp1D->result );
 }
 
+/*----------------------BinaryPredicate1D instance definitions ----------------------------*/
+static PyMethodDef BPy_BinaryPredicate1D_methods[] = {
+	{"getName", ( PyCFunction ) BinaryPredicate1D_getName, METH_NOARGS, BinaryPredicate1D_getName___doc__},
+	{NULL, NULL, 0, NULL}
+};
+
+/*-----------------------BPy_BinaryPredicate1D type definition ------------------------------*/
+PyTypeObject BinaryPredicate1D_Type = {
+	PyVarObject_HEAD_INIT(NULL, 0)
+	"BinaryPredicate1D",            /* tp_name */
+	sizeof(BPy_BinaryPredicate1D),  /* tp_basicsize */
+	0,                              /* tp_itemsize */
+	(destructor)BinaryPredicate1D___dealloc__, /* tp_dealloc */
+	0,                              /* tp_print */
+	0,                              /* tp_getattr */
+	0,                              /* tp_setattr */
+	0,                              /* tp_reserved */
+	(reprfunc)BinaryPredicate1D___repr__, /* tp_repr */
+	0,                              /* tp_as_number */
+	0,                              /* tp_as_sequence */
+	0,                              /* tp_as_mapping */
+	0,                              /* tp_hash  */
+	(ternaryfunc)BinaryPredicate1D___call__, /* tp_call */
+	0,                              /* tp_str */
+	0,                              /* tp_getattro */
+	0,                              /* tp_setattro */
+	0,                              /* tp_as_buffer */
+	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
+	BinaryPredicate1D___doc__,      /* tp_doc */
+	0,                              /* tp_traverse */
+	0,                              /* tp_clear */
+	0,                              /* tp_richcompare */
+	0,                              /* tp_weaklistoffset */
+	0,                              /* tp_iter */
+	0,                              /* tp_iternext */
+	BPy_BinaryPredicate1D_methods,  /* tp_methods */
+	0,                              /* tp_members */
+	0,                              /* tp_getset */
+	0,                              /* tp_base */
+	0,                              /* tp_dict */
+	0,                              /* tp_descr_get */
+	0,                              /* tp_descr_set */
+	0,                              /* tp_dictoffset */
+	(initproc)BinaryPredicate1D___init__, /* tp_init */
+	0,                              /* tp_alloc */
+	PyType_GenericNew,              /* tp_new */
+};
 
 ///////////////////////////////////////////////////////////////////////////////////////////