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, 85 insertions, 63 deletions

diff --git a/source/blender/freestyle/intern/python/BPy_UnaryPredicate1D.cpp b/source/blender/freestyle/intern/python/BPy_UnaryPredicate1D.cpp
index be0062644fd..8f68bba17b1 100644
--- a/source/blender/freestyle/intern/python/BPy_UnaryPredicate1D.cpp
+++ b/source/blender/freestyle/intern/python/BPy_UnaryPredicate1D.cpp
@@ -19,63 +19,6 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for UnaryPredicate1D instance  -----------*/
-static int UnaryPredicate1D___init__(BPy_UnaryPredicate1D *self, PyObject *args, PyObject *kwds);
-static void UnaryPredicate1D___dealloc__(BPy_UnaryPredicate1D *self);
-static PyObject * UnaryPredicate1D___repr__(BPy_UnaryPredicate1D *self);
-static PyObject * UnaryPredicate1D___call__( BPy_UnaryPredicate1D *self, PyObject *args, PyObject *kwds);
-
-static PyObject * UnaryPredicate1D_getName( BPy_UnaryPredicate1D *self, PyObject *args);
-
-/*----------------------UnaryPredicate1D instance definitions ----------------------------*/
-static PyMethodDef BPy_UnaryPredicate1D_methods[] = {
-	{"getName", ( PyCFunction ) UnaryPredicate1D_getName, METH_NOARGS, ""},
-	{NULL, NULL, 0, NULL}
-};
-
-/*-----------------------BPy_UnaryPredicate1D type definition ------------------------------*/
-
-PyTypeObject UnaryPredicate1D_Type = {
-	PyVarObject_HEAD_INIT(NULL, 0)
-	"UnaryPredicate1D",             /* tp_name */
-	sizeof(BPy_UnaryPredicate1D),   /* tp_basicsize */
-	0,                              /* tp_itemsize */
-	(destructor)UnaryPredicate1D___dealloc__, /* tp_dealloc */
-	0,                              /* tp_print */
-	0,                              /* tp_getattr */
-	0,                              /* tp_setattr */
-	0,                              /* tp_reserved */
-	(reprfunc)UnaryPredicate1D___repr__, /* tp_repr */
-	0,                              /* tp_as_number */
-	0,                              /* tp_as_sequence */
-	0,                              /* tp_as_mapping */
-	0,                              /* tp_hash  */
-	(ternaryfunc)UnaryPredicate1D___call__, /* tp_call */
-	0,                              /* tp_str */
-	0,                              /* tp_getattro */
-	0,                              /* tp_setattro */
-	0,                              /* tp_as_buffer */
-	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"UnaryPredicate1D objects",      /* tp_doc */
-	0,                              /* tp_traverse */
-	0,                              /* tp_clear */
-	0,                              /* tp_richcompare */
-	0,                              /* tp_weaklistoffset */
-	0,                              /* tp_iter */
-	0,                              /* tp_iternext */
-	BPy_UnaryPredicate1D_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)UnaryPredicate1D___init__, /* tp_init */
-	0,                              /* tp_alloc */
-	PyType_GenericNew,              /* tp_new */
-};
-
 //-------------------MODULE INITIALIZATION--------------------------------
 int UnaryPredicate1D_Init( PyObject *module )
 {
@@ -137,7 +80,28 @@ int UnaryPredicate1D_Init( PyObject *module )
 
 //------------------------INSTANCE METHODS ----------------------------------
 
-int UnaryPredicate1D___init__(BPy_UnaryPredicate1D *self, PyObject *args, PyObject *kwds)
+static char UnaryPredicate1D___doc__[] =
+"Base class for unary predicates that work on :class:`Interface1D`.  A\n"
+"UnaryPredicate1D is a functor that evaluates a condition on a\n"
+"Interface1D and returns true or false depending on whether this\n"
+"condition is satisfied or not.  The UnaryPredicate1D is used by\n"
+"invoking its __call__() method.  Any inherited class must overload the\n"
+"__call__() method.\n"
+"\n"
+".. method:: __init__()\n"
+"\n"
+"   Default constructor.\n"
+"\n"
+".. method:: __call__(inter)\n"
+"\n"
+"   Must be overload by inherited classes.\n"
+"\n"
+"   :arg inter: The Interface1D on which we wish to evaluate the predicate.\n"
+"   :type inter: :class:`Interface1D`\n"
+"   :return: True if the condition is satisfied, false otherwise.\n"
+"   :rtype: bool\n";
+
+static int UnaryPredicate1D___init__(BPy_UnaryPredicate1D *self, PyObject *args, PyObject *kwds)
 {
 	if( !PyArg_ParseTuple(args, "") )	
 		return -1;
@@ -146,21 +110,31 @@ int UnaryPredicate1D___init__(BPy_UnaryPredicate1D *self, PyObject *args, PyObje
 	return 0;
 }
 
-void UnaryPredicate1D___dealloc__(BPy_UnaryPredicate1D* self)
+static void UnaryPredicate1D___dealloc__(BPy_UnaryPredicate1D* self)
 {
 	if (self->up1D)
 		delete self->up1D;
     Py_TYPE(self)->tp_free((PyObject*)self);
 }
 
-
-PyObject * UnaryPredicate1D___repr__(BPy_UnaryPredicate1D* self)
+static PyObject * UnaryPredicate1D___repr__(BPy_UnaryPredicate1D* self)
 {
     return PyUnicode_FromFormat("type: %s - address: %p", self->up1D->getName().c_str(), self->up1D );
 }
 
-
-PyObject * UnaryPredicate1D_getName( BPy_UnaryPredicate1D *self, PyObject *args)
+static char UnaryPredicate1D_getName___doc__[] =
+".. method:: getName()\n"
+"\n"
+"   Returns the string of the name of the UnaryPredicate1D.\n"
+"\n"
+"   Reimplemented in TrueUP1D, FalseUP1D, QuantitativeInvisibilityUP1D,\n"
+"   ContourUP1D, ExternalContourUP1D, EqualToTimeStampUP1D,\n"
+"   EqualToChainingTimeStampUP1D, ShapeUP1D, and DensityLowerThanUP1D.\n"
+"\n"
+"   :return: \n"
+"   :rtype: string\n";
+
+static PyObject * UnaryPredicate1D_getName( BPy_UnaryPredicate1D *self, PyObject *args)
 {
 	return PyUnicode_FromFormat( self->up1D->getName().c_str() );
 }
@@ -197,6 +171,54 @@ static PyObject * UnaryPredicate1D___call__( BPy_UnaryPredicate1D *self, PyObjec
 	return PyBool_from_bool( self->up1D->result );
 }
 
+/*----------------------UnaryPredicate1D instance definitions ----------------------------*/
+static PyMethodDef BPy_UnaryPredicate1D_methods[] = {
+	{"getName", ( PyCFunction ) UnaryPredicate1D_getName, METH_NOARGS, UnaryPredicate1D_getName___doc__},
+	{NULL, NULL, 0, NULL}
+};
+
+/*-----------------------BPy_UnaryPredicate1D type definition ------------------------------*/
+
+PyTypeObject UnaryPredicate1D_Type = {
+	PyVarObject_HEAD_INIT(NULL, 0)
+	"UnaryPredicate1D",             /* tp_name */
+	sizeof(BPy_UnaryPredicate1D),   /* tp_basicsize */
+	0,                              /* tp_itemsize */
+	(destructor)UnaryPredicate1D___dealloc__, /* tp_dealloc */
+	0,                              /* tp_print */
+	0,                              /* tp_getattr */
+	0,                              /* tp_setattr */
+	0,                              /* tp_reserved */
+	(reprfunc)UnaryPredicate1D___repr__, /* tp_repr */
+	0,                              /* tp_as_number */
+	0,                              /* tp_as_sequence */
+	0,                              /* tp_as_mapping */
+	0,                              /* tp_hash  */
+	(ternaryfunc)UnaryPredicate1D___call__, /* tp_call */
+	0,                              /* tp_str */
+	0,                              /* tp_getattro */
+	0,                              /* tp_setattro */
+	0,                              /* tp_as_buffer */
+	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
+	UnaryPredicate1D___doc__,       /* tp_doc */
+	0,                              /* tp_traverse */
+	0,                              /* tp_clear */
+	0,                              /* tp_richcompare */
+	0,                              /* tp_weaklistoffset */
+	0,                              /* tp_iter */
+	0,                              /* tp_iternext */
+	BPy_UnaryPredicate1D_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)UnaryPredicate1D___init__, /* tp_init */
+	0,                              /* tp_alloc */
+	PyType_GenericNew,              /* tp_new */
+};
 
 ///////////////////////////////////////////////////////////////////////////////////////////