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, 73 insertions, 54 deletions

diff --git a/source/blender/freestyle/intern/python/Iterator/BPy_orientedViewEdgeIterator.cpp b/source/blender/freestyle/intern/python/Iterator/BPy_orientedViewEdgeIterator.cpp
index 27f71d4cfc0..c080426daa8 100644
--- a/source/blender/freestyle/intern/python/Iterator/BPy_orientedViewEdgeIterator.cpp
+++ b/source/blender/freestyle/intern/python/Iterator/BPy_orientedViewEdgeIterator.cpp
@@ -8,16 +8,83 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for orientedViewEdgeIterator instance  -----------*/
-static int orientedViewEdgeIterator___init__(BPy_orientedViewEdgeIterator *self, PyObject *args);
-static PyObject * orientedViewEdgeIterator_iternext(BPy_orientedViewEdgeIterator *self);
+//------------------------INSTANCE METHODS ----------------------------------
+
+static char orientedViewEdgeIterator___doc__[] =
+"Class representing an iterator over oriented ViewEdges around a\n"
+":class:`ViewVertex`.  This iterator allows a CCW iteration (in the image\n"
+"plane).  An instance of an orientedViewEdgeIterator can only be\n"
+"obtained from a ViewVertex by calling edgesBegin() or edgesEnd().\n"
+"\n"
+".. method:: __init__()\n"
+"\n"
+"   Default constructor.\n"
+"\n"
+".. method:: __init__(iBrother)\n"
+"\n"
+"   Copy constructor.\n"
+"\n"
+"   :arg iBrother: An orientedViewEdgeIterator object.\n"
+"   :type iBrother: :class:`orientedViewEdgeIterator`\n";
+
+static int orientedViewEdgeIterator___init__(BPy_orientedViewEdgeIterator *self, PyObject *args )
+{	
+	PyObject *obj = 0;
+
+	if (!( PyArg_ParseTuple(args, "|O", &obj) ))
+	    return -1;
+
+	if( !obj )
+		self->ove_it = new ViewVertexInternal::orientedViewEdgeIterator();
+	else if( BPy_orientedViewEdgeIterator_Check(obj) )
+		self->ove_it = new ViewVertexInternal::orientedViewEdgeIterator(*( ((BPy_orientedViewEdgeIterator *) obj)->ove_it ));
+	else {
+		PyErr_SetString(PyExc_TypeError, "invalid argument");
+		return -1;
+	}
+	
+	self->py_it.it = self->ove_it;
+	self->reversed = 0;
+	
+	return 0;
+}
 
-static PyObject * orientedViewEdgeIterator_getObject(BPy_orientedViewEdgeIterator *self);
+static PyObject * orientedViewEdgeIterator_iternext( BPy_orientedViewEdgeIterator *self ) {
+	ViewVertex::directedViewEdge *dve;
+	if (self->reversed) {
+		if (self->ove_it->isBegin()) {
+			PyErr_SetNone(PyExc_StopIteration);
+			return NULL;
+		}
+		self->ove_it->decrement();
+		dve = self->ove_it->operator->();
+	} else {
+		if (self->ove_it->isEnd()) {
+			PyErr_SetNone(PyExc_StopIteration);
+			return NULL;
+		}
+		dve = self->ove_it->operator->();
+		self->ove_it->increment();
+	}
+	return BPy_directedViewEdge_from_directedViewEdge( *dve );
+}
 
+static char orientedViewEdgeIterator_getObject___doc__[] =
+".. method:: getObject()\n"
+"\n"
+"   Returns the pointed oriented ViewEdge.\n"
+"\n"
+"   :return: A tuple of the pointed ViewEdge and a boolean value.  If\n"
+"      the boolean value is true, the ViewEdge is incoming.\n"
+"   :rtype: (:class:`directedViewEdge`, bool)\n";
+
+static PyObject * orientedViewEdgeIterator_getObject( BPy_orientedViewEdgeIterator *self) {
+	return BPy_directedViewEdge_from_directedViewEdge( self->ove_it->operator*() );
+}
 
 /*----------------------orientedViewEdgeIterator instance definitions ----------------------------*/
 static PyMethodDef BPy_orientedViewEdgeIterator_methods[] = {
-	{"getObject", ( PyCFunction ) orientedViewEdgeIterator_getObject, METH_NOARGS, "() Get object referenced by the iterator"},
+	{"getObject", ( PyCFunction ) orientedViewEdgeIterator_getObject, METH_NOARGS, orientedViewEdgeIterator_getObject___doc__},
 	{NULL, NULL, 0, NULL}
 };
 
@@ -44,7 +111,7 @@ PyTypeObject orientedViewEdgeIterator_Type = {
 	0,                              /* tp_setattro */
 	0,                              /* tp_as_buffer */
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"orientedViewEdgeIterator objects", /* tp_doc */
+	orientedViewEdgeIterator___doc__, /* tp_doc */
 	0,                              /* tp_traverse */
 	0,                              /* tp_clear */
 	0,                              /* tp_richcompare */
@@ -64,54 +131,6 @@ PyTypeObject orientedViewEdgeIterator_Type = {
 	0,                              /* tp_new */
 };
 
-//------------------------INSTANCE METHODS ----------------------------------
-
-int orientedViewEdgeIterator___init__(BPy_orientedViewEdgeIterator *self, PyObject *args )
-{	
-	PyObject *obj = 0;
-
-	if (!( PyArg_ParseTuple(args, "|O", &obj) ))
-	    return -1;
-
-	if( !obj )
-		self->ove_it = new ViewVertexInternal::orientedViewEdgeIterator();
-	else if( BPy_orientedViewEdgeIterator_Check(obj) )
-		self->ove_it = new ViewVertexInternal::orientedViewEdgeIterator(*( ((BPy_orientedViewEdgeIterator *) obj)->ove_it ));
-	else {
-		PyErr_SetString(PyExc_TypeError, "invalid argument");
-		return -1;
-	}
-	
-	self->py_it.it = self->ove_it;
-	self->reversed = 0;
-	
-	return 0;
-}
-
-PyObject * orientedViewEdgeIterator_iternext( BPy_orientedViewEdgeIterator *self ) {
-	ViewVertex::directedViewEdge *dve;
-	if (self->reversed) {
-		if (self->ove_it->isBegin()) {
-			PyErr_SetNone(PyExc_StopIteration);
-			return NULL;
-		}
-		self->ove_it->decrement();
-		dve = self->ove_it->operator->();
-	} else {
-		if (self->ove_it->isEnd()) {
-			PyErr_SetNone(PyExc_StopIteration);
-			return NULL;
-		}
-		dve = self->ove_it->operator->();
-		self->ove_it->increment();
-	}
-	return BPy_directedViewEdge_from_directedViewEdge( *dve );
-}
-
-PyObject * orientedViewEdgeIterator_getObject( BPy_orientedViewEdgeIterator *self) {
-	return BPy_directedViewEdge_from_directedViewEdge( self->ove_it->operator*() );
-}
-
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus