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

diff --git a/source/blender/freestyle/intern/python/Iterator/BPy_AdjacencyIterator.cpp b/source/blender/freestyle/intern/python/Iterator/BPy_AdjacencyIterator.cpp
index dcc56b406e1..a4fe0164f78 100644
--- a/source/blender/freestyle/intern/python/Iterator/BPy_AdjacencyIterator.cpp
+++ b/source/blender/freestyle/intern/python/Iterator/BPy_AdjacencyIterator.cpp
@@ -9,66 +9,35 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for AdjacencyIterator instance  -----------*/
-static int AdjacencyIterator___init__(BPy_AdjacencyIterator *self, PyObject *args);
-static PyObject * AdjacencyIterator_iternext(BPy_AdjacencyIterator *self);
-
-static PyObject * AdjacencyIterator_isIncoming(BPy_AdjacencyIterator *self);
-static PyObject * AdjacencyIterator_getObject(BPy_AdjacencyIterator *self);
-
-/*----------------------AdjacencyIterator instance definitions ----------------------------*/
-static PyMethodDef BPy_AdjacencyIterator_methods[] = {
-	{"isIncoming", ( PyCFunction ) AdjacencyIterator_isIncoming, METH_NOARGS, "() Returns true if the current ViewEdge is is coming towards the iteration vertex. False otherwise."},
-	{"getObject", ( PyCFunction ) AdjacencyIterator_getObject, METH_NOARGS, "() Get object referenced by the iterator"},
-	{NULL, NULL, 0, NULL}
-};
-
-/*-----------------------BPy_AdjacencyIterator type definition ------------------------------*/
-
-PyTypeObject AdjacencyIterator_Type = {
-	PyVarObject_HEAD_INIT(NULL, 0)
-	"AdjacencyIterator",            /* tp_name */
-	sizeof(BPy_AdjacencyIterator),  /* tp_basicsize */
-	0,                              /* tp_itemsize */
-	0,                              /* tp_dealloc */
-	0,                              /* tp_print */
-	0,                              /* tp_getattr */
-	0,                              /* tp_setattr */
-	0,                              /* tp_reserved */
-	0,                              /* tp_repr */
-	0,                              /* tp_as_number */
-	0,                              /* tp_as_sequence */
-	0,                              /* tp_as_mapping */
-	0,                              /* tp_hash  */
-	0,                              /* tp_call */
-	0,                              /* tp_str */
-	0,                              /* tp_getattro */
-	0,                              /* tp_setattro */
-	0,                              /* tp_as_buffer */
-	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"AdjacencyIterator objects",    /* tp_doc */
-	0,                              /* tp_traverse */
-	0,                              /* tp_clear */
-	0,                              /* tp_richcompare */
-	0,                              /* tp_weaklistoffset */
-	PyObject_SelfIter,              /* tp_iter */
-	(iternextfunc)AdjacencyIterator_iternext, /* tp_iternext */
-	BPy_AdjacencyIterator_methods,  /* tp_methods */
-	0,                              /* tp_members */
-	0,                              /* tp_getset */
-	&Iterator_Type,                 /* tp_base */
-	0,                              /* tp_dict */
-	0,                              /* tp_descr_get */
-	0,                              /* tp_descr_set */
-	0,                              /* tp_dictoffset */
-	(initproc)AdjacencyIterator___init__, /* tp_init */
-	0,                              /* tp_alloc */
-	0,                              /* tp_new */
-};
-
 //------------------------INSTANCE METHODS ----------------------------------
 
-int AdjacencyIterator___init__(BPy_AdjacencyIterator *self, PyObject *args )
+static char AdjacencyIterator___doc__[] =
+"Class for representing adjacency iterators used in the chaining\n"
+"process.  An AdjacencyIterator is created in the increment() and\n"
+"decrement() methods of a :class:`ChainingIterator` and passed to the\n"
+"traverse() method of the ChainingIterator.\n"
+"\n"
+".. method:: __init__(iVertex, iRestrictToSelection=True, iRestrictToUnvisited=True)\n"
+"\n"
+"   Builds a AdjacencyIterator object.\n"
+"\n"
+"   :arg iVertex: The vertex which is the next crossing.\n"
+"   :type iVertex: :class:`ViewVertex`\n"
+"   :arg iRestrictToSelection: Indicates whether to force the chaining\n"
+"      to stay within the set of selected ViewEdges or not.\n"
+"   :type iRestrictToSelection: bool\n"
+"   :arg iRestrictToUnvisited: Indicates whether a ViewEdge that has\n"
+"      already been chained must be ignored ot not.\n"
+"   :type iRestrictToUnvisited: bool\n"
+"\n"
+".. method:: __init__(it)\n"
+"\n"
+"   Copy constructor.\n"
+"\n"
+"   :arg it: An AdjacencyIterator object.\n"
+"   :type it: :class:`AdjacencyIterator`\n";
+
+static int AdjacencyIterator___init__(BPy_AdjacencyIterator *self, PyObject *args )
 {	
 	PyObject *obj1 = 0, *obj2 = 0 , *obj3 = 0;
 
@@ -98,7 +67,7 @@ int AdjacencyIterator___init__(BPy_AdjacencyIterator *self, PyObject *args )
 
 }
 
-PyObject * AdjacencyIterator_iternext(BPy_AdjacencyIterator *self) {
+static PyObject * AdjacencyIterator_iternext(BPy_AdjacencyIterator *self) {
 	if (self->a_it->isEnd()) {
 		PyErr_SetNone(PyExc_StopIteration);
 		return NULL;
@@ -108,11 +77,29 @@ PyObject * AdjacencyIterator_iternext(BPy_AdjacencyIterator *self) {
 	return BPy_ViewEdge_from_ViewEdge( *ve );
 }
 
-PyObject * AdjacencyIterator_isIncoming(BPy_AdjacencyIterator *self) {
+static char AdjacencyIterator_isIncoming___doc__[] =
+".. method:: isIncoming()\n"
+"\n"
+"   Returns true if the current ViewEdge is coming towards the\n"
+"   iteration vertex.  False otherwise.\n"
+"\n"
+"   :return: True if the current ViewEdge is coming towards the\n"
+"      iteration vertex\n"
+"   :rtype: bool\n";
+
+static PyObject * AdjacencyIterator_isIncoming(BPy_AdjacencyIterator *self) {
 	return PyBool_from_bool(self->a_it->isIncoming());
 }
 
-PyObject * AdjacencyIterator_getObject(BPy_AdjacencyIterator *self) {
+static char AdjacencyIterator_getObject___doc__[] =
+".. method:: getObject()\n"
+"\n"
+"   Returns the pointed ViewEdge.\n"
+"\n"
+"   :return: The pointed ViewEdge.\n"
+"   :rtype: ViewEdge* operator\n";
+
+static PyObject * AdjacencyIterator_getObject(BPy_AdjacencyIterator *self) {
 	
 	ViewEdge *ve = self->a_it->operator*();
 	if( ve )
@@ -121,6 +108,55 @@ PyObject * AdjacencyIterator_getObject(BPy_AdjacencyIterator *self) {
 	Py_RETURN_NONE;
 }
 
+/*----------------------AdjacencyIterator instance definitions ----------------------------*/
+static PyMethodDef BPy_AdjacencyIterator_methods[] = {
+	{"isIncoming", ( PyCFunction ) AdjacencyIterator_isIncoming, METH_NOARGS, AdjacencyIterator_isIncoming___doc__},
+	{"getObject", ( PyCFunction ) AdjacencyIterator_getObject, METH_NOARGS, AdjacencyIterator_getObject___doc__},
+	{NULL, NULL, 0, NULL}
+};
+
+/*-----------------------BPy_AdjacencyIterator type definition ------------------------------*/
+
+PyTypeObject AdjacencyIterator_Type = {
+	PyVarObject_HEAD_INIT(NULL, 0)
+	"AdjacencyIterator",            /* tp_name */
+	sizeof(BPy_AdjacencyIterator),  /* tp_basicsize */
+	0,                              /* tp_itemsize */
+	0,                              /* tp_dealloc */
+	0,                              /* tp_print */
+	0,                              /* tp_getattr */
+	0,                              /* tp_setattr */
+	0,                              /* tp_reserved */
+	0,                              /* tp_repr */
+	0,                              /* tp_as_number */
+	0,                              /* tp_as_sequence */
+	0,                              /* tp_as_mapping */
+	0,                              /* tp_hash  */
+	0,                              /* tp_call */
+	0,                              /* tp_str */
+	0,                              /* tp_getattro */
+	0,                              /* tp_setattro */
+	0,                              /* tp_as_buffer */
+	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
+	AdjacencyIterator___doc__,      /* tp_doc */
+	0,                              /* tp_traverse */
+	0,                              /* tp_clear */
+	0,                              /* tp_richcompare */
+	0,                              /* tp_weaklistoffset */
+	PyObject_SelfIter,              /* tp_iter */
+	(iternextfunc)AdjacencyIterator_iternext, /* tp_iternext */
+	BPy_AdjacencyIterator_methods,  /* tp_methods */
+	0,                              /* tp_members */
+	0,                              /* tp_getset */
+	&Iterator_Type,                 /* tp_base */
+	0,                              /* tp_dict */
+	0,                              /* tp_descr_get */
+	0,                              /* tp_descr_set */
+	0,                              /* tp_dictoffset */
+	(initproc)AdjacencyIterator___init__, /* tp_init */
+	0,                              /* tp_alloc */
+	0,                              /* tp_new */
+};
 
 ///////////////////////////////////////////////////////////////////////////////////////////