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, 91 insertions, 61 deletions

diff --git a/source/blender/freestyle/intern/python/UnaryFunction1D/BPy_UnaryFunction1DVec3f.cpp b/source/blender/freestyle/intern/python/UnaryFunction1D/BPy_UnaryFunction1DVec3f.cpp
index 05ba1175690..ae31fd5c9fd 100644
--- a/source/blender/freestyle/intern/python/UnaryFunction1D/BPy_UnaryFunction1DVec3f.cpp
+++ b/source/blender/freestyle/intern/python/UnaryFunction1D/BPy_UnaryFunction1DVec3f.cpp
@@ -12,67 +12,6 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for UnaryFunction1DVec3f instance  -----------*/
-static int UnaryFunction1DVec3f___init__(BPy_UnaryFunction1DVec3f* self, PyObject *args);
-static void UnaryFunction1DVec3f___dealloc__(BPy_UnaryFunction1DVec3f* self);
-static PyObject * UnaryFunction1DVec3f___repr__(BPy_UnaryFunction1DVec3f* self);
-
-static PyObject * UnaryFunction1DVec3f_getName( BPy_UnaryFunction1DVec3f *self);
-static PyObject * UnaryFunction1DVec3f___call__( BPy_UnaryFunction1DVec3f *self, PyObject *args, PyObject *kwds);
-static PyObject * UnaryFunction1DVec3f_setIntegrationType(BPy_UnaryFunction1DVec3f* self, PyObject *args);
-static PyObject * UnaryFunction1DVec3f_getIntegrationType(BPy_UnaryFunction1DVec3f* self);
-
-/*----------------------UnaryFunction1DVec3f instance definitions ----------------------------*/
-static PyMethodDef BPy_UnaryFunction1DVec3f_methods[] = {
-	{"getName", ( PyCFunction ) UnaryFunction1DVec3f_getName, METH_NOARGS, "() Returns the string of the name of the unary 1D function."},
-	{"setIntegrationType", ( PyCFunction ) UnaryFunction1DVec3f_setIntegrationType, METH_VARARGS, "(IntegrationType i) Sets the integration method" },
-	{"getIntegrationType", ( PyCFunction ) UnaryFunction1DVec3f_getIntegrationType, METH_NOARGS, "() Returns the integration method." },
-	{NULL, NULL, 0, NULL}
-};
-
-/*-----------------------BPy_UnaryFunction1DVec3f type definition ------------------------------*/
-
-PyTypeObject UnaryFunction1DVec3f_Type = {
-	PyVarObject_HEAD_INIT(NULL, 0)
-	"UnaryFunction1DVec3f",         /* tp_name */
-	sizeof(BPy_UnaryFunction1DVec3f), /* tp_basicsize */
-	0,                              /* tp_itemsize */
-	(destructor)UnaryFunction1DVec3f___dealloc__, /* tp_dealloc */
-	0,                              /* tp_print */
-	0,                              /* tp_getattr */
-	0,                              /* tp_setattr */
-	0,                              /* tp_reserved */
-	(reprfunc)UnaryFunction1DVec3f___repr__, /* tp_repr */
-	0,                              /* tp_as_number */
-	0,                              /* tp_as_sequence */
-	0,                              /* tp_as_mapping */
-	0,                              /* tp_hash  */
-	(ternaryfunc)UnaryFunction1DVec3f___call__, /* tp_call */
-	0,                              /* tp_str */
-	0,                              /* tp_getattro */
-	0,                              /* tp_setattro */
-	0,                              /* tp_as_buffer */
-	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"UnaryFunction1DVec3f objects", /* tp_doc */
-	0,                              /* tp_traverse */
-	0,                              /* tp_clear */
-	0,                              /* tp_richcompare */
-	0,                              /* tp_weaklistoffset */
-	0,                              /* tp_iter */
-	0,                              /* tp_iternext */
-	BPy_UnaryFunction1DVec3f_methods, /* tp_methods */
-	0,                              /* tp_members */
-	0,                              /* tp_getset */
-	&UnaryFunction1D_Type,          /* tp_base */
-	0,                              /* tp_dict */
-	0,                              /* tp_descr_get */
-	0,                              /* tp_descr_set */
-	0,                              /* tp_dictoffset */
-	(initproc)UnaryFunction1DVec3f___init__, /* tp_init */
-	0,                              /* tp_alloc */
-	0,                              /* tp_new */
-};
-
 //-------------------MODULE INITIALIZATION--------------------------------
 
 int UnaryFunction1DVec3f_Init( PyObject *module ) {
@@ -95,6 +34,22 @@ int UnaryFunction1DVec3f_Init( PyObject *module ) {
 
 //------------------------INSTANCE METHODS ----------------------------------
 
+static char UnaryFunction1DVec3f___doc__[] =
+"Base class for unary functions (functors) that work on\n"
+":class:`Interface1D` and return a 3D vector.\n"
+"\n"
+".. method:: __init__()\n"
+"\n"
+"   Default constructor.\n"
+"\n"
+".. method:: __init__(integration)\n"
+"\n"
+"   Builds a unary 1D function using the integration method given as\n"
+"   argument.\n"
+"\n"
+"   :arg integration: An integration method.\n"
+"   :type integration: :class:`IntegrationType`\n";
+
 int UnaryFunction1DVec3f___init__(BPy_UnaryFunction1DVec3f* self, PyObject *args)
 {
 	PyObject *obj = 0;
@@ -125,6 +80,14 @@ PyObject * UnaryFunction1DVec3f___repr__(BPy_UnaryFunction1DVec3f* self)
 	return PyUnicode_FromFormat("type: %s - address: %p", self->uf1D_vec3f->getName().c_str(), self->uf1D_vec3f );
 }
 
+static char UnaryFunction1DVec3f_getName___doc__[] =
+".. method:: getName()\n"
+"\n"
+"   Returns the name of the unary 1D function.\n"
+"\n"
+"   :return: The name of the unary 1D function.\n"
+"   :rtype: string\n";
+
 PyObject * UnaryFunction1DVec3f_getName( BPy_UnaryFunction1DVec3f *self )
 {
 	return PyUnicode_FromFormat( self->uf1D_vec3f->getName().c_str() );
@@ -156,6 +119,14 @@ PyObject * UnaryFunction1DVec3f___call__( BPy_UnaryFunction1DVec3f *self, PyObje
 
 }
 
+static char UnaryFunction1DVec3f_setIntegrationType___doc__[] =
+".. method:: setIntegrationType(integration)\n"
+"\n"
+"   Sets the integration method.\n"
+"\n"
+"   :arg integration: An integration method.\n"
+"   :type integration: :class:`IntegrationType`\n";
+
 PyObject * UnaryFunction1DVec3f_setIntegrationType(BPy_UnaryFunction1DVec3f* self, PyObject *args)
 {
 	PyObject *obj;
@@ -167,10 +138,69 @@ PyObject * UnaryFunction1DVec3f_setIntegrationType(BPy_UnaryFunction1DVec3f* sel
 	Py_RETURN_NONE;
 }
 
+static char UnaryFunction1DVec3f_getIntegrationType___doc__[] =
+".. method:: getIntegrationType(integration)\n"
+"\n"
+"   Returns the integration method.\n"
+"\n"
+"   :return: The integration method.\n"
+"   :rtype: :class:`IntegrationType`\n";
+
 PyObject * UnaryFunction1DVec3f_getIntegrationType(BPy_UnaryFunction1DVec3f* self) {
 	return BPy_IntegrationType_from_IntegrationType( self->uf1D_vec3f->getIntegrationType() );
 }
 
+/*----------------------UnaryFunction1DVec3f instance definitions ----------------------------*/
+static PyMethodDef BPy_UnaryFunction1DVec3f_methods[] = {
+	{"getName", ( PyCFunction ) UnaryFunction1DVec3f_getName, METH_NOARGS, UnaryFunction1DVec3f_getName___doc__},
+	{"setIntegrationType", ( PyCFunction ) UnaryFunction1DVec3f_setIntegrationType, METH_VARARGS, UnaryFunction1DVec3f_setIntegrationType___doc__},
+	{"getIntegrationType", ( PyCFunction ) UnaryFunction1DVec3f_getIntegrationType, METH_NOARGS, UnaryFunction1DVec3f_getIntegrationType___doc__},
+	{NULL, NULL, 0, NULL}
+};
+
+/*-----------------------BPy_UnaryFunction1DVec3f type definition ------------------------------*/
+
+PyTypeObject UnaryFunction1DVec3f_Type = {
+	PyVarObject_HEAD_INIT(NULL, 0)
+	"UnaryFunction1DVec3f",         /* tp_name */
+	sizeof(BPy_UnaryFunction1DVec3f), /* tp_basicsize */
+	0,                              /* tp_itemsize */
+	(destructor)UnaryFunction1DVec3f___dealloc__, /* tp_dealloc */
+	0,                              /* tp_print */
+	0,                              /* tp_getattr */
+	0,                              /* tp_setattr */
+	0,                              /* tp_reserved */
+	(reprfunc)UnaryFunction1DVec3f___repr__, /* tp_repr */
+	0,                              /* tp_as_number */
+	0,                              /* tp_as_sequence */
+	0,                              /* tp_as_mapping */
+	0,                              /* tp_hash  */
+	(ternaryfunc)UnaryFunction1DVec3f___call__, /* tp_call */
+	0,                              /* tp_str */
+	0,                              /* tp_getattro */
+	0,                              /* tp_setattro */
+	0,                              /* tp_as_buffer */
+	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
+	UnaryFunction1DVec3f___doc__,   /* tp_doc */
+	0,                              /* tp_traverse */
+	0,                              /* tp_clear */
+	0,                              /* tp_richcompare */
+	0,                              /* tp_weaklistoffset */
+	0,                              /* tp_iter */
+	0,                              /* tp_iternext */
+	BPy_UnaryFunction1DVec3f_methods, /* tp_methods */
+	0,                              /* tp_members */
+	0,                              /* tp_getset */
+	&UnaryFunction1D_Type,          /* tp_base */
+	0,                              /* tp_dict */
+	0,                              /* tp_descr_get */
+	0,                              /* tp_descr_set */
+	0,                              /* tp_dictoffset */
+	(initproc)UnaryFunction1DVec3f___init__, /* tp_init */
+	0,                              /* tp_alloc */
+	0,                              /* tp_new */
+};
+
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus