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, 142 insertions, 76 deletions

diff --git a/source/blender/freestyle/intern/python/Interface0D/ViewVertex/BPy_TVertex.cpp b/source/blender/freestyle/intern/python/Interface0D/ViewVertex/BPy_TVertex.cpp
index 90b6e578b4d..f7e36e753b5 100644
--- a/source/blender/freestyle/intern/python/Interface0D/ViewVertex/BPy_TVertex.cpp
+++ b/source/blender/freestyle/intern/python/Interface0D/ViewVertex/BPy_TVertex.cpp
@@ -12,76 +12,27 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for TVertex___init__ instance  -----------*/
-static int TVertex___init__(BPy_TVertex *self, PyObject *args, PyObject *kwds);
-
-static PyObject * TVertex_frontSVertex( BPy_TVertex *self );
-static PyObject * TVertex_backSVertex( BPy_TVertex *self );
-static PyObject * TVertex_setFrontSVertex( BPy_TVertex *self, PyObject *args); 
-static PyObject * TVertex_setBackSVertex( BPy_TVertex *self, PyObject *args); 
-static PyObject * TVertex_setId( BPy_TVertex *self, PyObject *args);
-static PyObject * TVertex_getSVertex( BPy_TVertex *self, PyObject *args);
-static PyObject * TVertex_mate( BPy_TVertex *self, PyObject *args);
-
-/*----------------------TVertex instance definitions ----------------------------*/
-static PyMethodDef BPy_TVertex_methods[] = {	
-//	{"__copy__", ( PyCFunction ) TVertex___copy__, METH_NOARGS, "() Cloning method."},
-	{"frontSVertex", ( PyCFunction ) TVertex_frontSVertex, METH_NOARGS, "() Returns the SVertex that is closer to the viewpoint. "},
-	{"backSVertex", ( PyCFunction ) TVertex_backSVertex, METH_NOARGS, "() Returns the SVertex that is further away from the viewpoint. "},
-	{"setFrontSVertex", ( PyCFunction ) TVertex_setFrontSVertex, METH_VARARGS, "(SVertex sv) Sets the SVertex that is closer to the viewpoint. "},
-	{"setBackSVertex", ( PyCFunction ) TVertex_setBackSVertex, METH_VARARGS, "(SVertex sv) Sets the SVertex that is further away from the viewpoint. "},
-	{"setId", ( PyCFunction ) TVertex_setId, METH_VARARGS, "(Id id) Sets the Id."},
-	{"getSVertex", ( PyCFunction ) TVertex_getSVertex, METH_VARARGS, "(FEdge fe) Returns the SVertex (among the 2) belonging to the FEdge iFEdge "},
-	{"mate", ( PyCFunction ) TVertex_mate, METH_VARARGS, "(ViewEdge ve) Returns the mate edge of iEdgeA. For example, if iEdgeA is frontEdgeA, then frontEdgeB is returned. If iEdgeA is frontEdgeB then frontEdgeA is returned. Same for back edges"},
-	{NULL, NULL, 0, NULL}
-};
-
-/*-----------------------BPy_TVertex type definition ------------------------------*/
-
-PyTypeObject TVertex_Type = {
-	PyVarObject_HEAD_INIT(NULL, 0)
-	"TVertex",                      /* tp_name */
-	sizeof(BPy_TVertex),            /* 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 */
-	"TVertex objects",              /* tp_doc */
-	0,                              /* tp_traverse */
-	0,                              /* tp_clear */
-	0,                              /* tp_richcompare */
-	0,                              /* tp_weaklistoffset */
-	0,                              /* tp_iter */
-	0,                              /* tp_iternext */
-	BPy_TVertex_methods,            /* tp_methods */
-	0,                              /* tp_members */
-	0,                              /* tp_getset */
-	&ViewVertex_Type,               /* tp_base */
-	0,                              /* tp_dict */
-	0,                              /* tp_descr_get */
-	0,                              /* tp_descr_set */
-	0,                              /* tp_dictoffset */
-	(initproc)TVertex___init__,     /* tp_init */
-	0,                              /* tp_alloc */
-	0,                              /* tp_new */
-};
-
 //------------------------INSTANCE METHODS ----------------------------------
 
-int TVertex___init__(BPy_TVertex *self, PyObject *args, PyObject *kwds)
+static char TVertex___doc__[] =
+"Class to define a T vertex, i.e. an intersection between two edges.\n"
+"It points towards two SVertex and four ViewEdges.  Among the\n"
+"ViewEdges, two are front and the other two are back.  Basically a\n"
+"front edge hides part of a back edge.  So, among the back edges, one\n"
+"is of invisibility N and the other of invisibility N+1.\n"
+"\n"
+".. method:: __init__()\n"
+"\n"
+"   Default constructor.\n"
+"\n"
+".. method:: __init__(iBrother)\n"
+"\n"
+"   Copy constructor.\n"
+"\n"
+"   :arg iBrother: A TVertex object.\n"
+"   :type iBrother: :class:`TVertex`\n";
+
+static int TVertex___init__(BPy_TVertex *self, PyObject *args, PyObject *kwds)
 {
     if( !PyArg_ParseTuple(args, "") )
         return -1;
@@ -93,8 +44,15 @@ int TVertex___init__(BPy_TVertex *self, PyObject *args, PyObject *kwds)
 	return 0;
 }
 
+static char TVertex_frontSVertex___doc__[] =
+".. method:: frontSVertex()\n"
+"\n"
+"   Returns the SVertex that is closer to the viewpoint.\n"
+"\n"
+"   :return: The SVertex that is closer to the viewpoint.\n"
+"   :rtype: :class:`SVertex`\n";
 
-PyObject * TVertex_frontSVertex( BPy_TVertex *self ) {
+static PyObject * TVertex_frontSVertex( BPy_TVertex *self ) {
 	SVertex *v = self->tv->frontSVertex();
 	if( v ){
 		return BPy_SVertex_from_SVertex( *v );
@@ -103,7 +61,15 @@ PyObject * TVertex_frontSVertex( BPy_TVertex *self ) {
 	Py_RETURN_NONE;
 }
 
-PyObject * TVertex_backSVertex( BPy_TVertex *self ) {
+static char TVertex_backSVertex___doc__[] =
+".. method:: backSVertex()\n"
+"\n"
+"   Returns the SVertex that is further away from the viewpoint.\n"
+"\n"
+"   :return: The SVertex that is further away from the viewpoint.\n"
+"   :rtype: :class:`SVertex`\n";
+
+static PyObject * TVertex_backSVertex( BPy_TVertex *self ) {
 	SVertex *v = self->tv->backSVertex();
 	if( v ){
 		return BPy_SVertex_from_SVertex( *v );
@@ -112,7 +78,15 @@ PyObject * TVertex_backSVertex( BPy_TVertex *self ) {
 	Py_RETURN_NONE;
 }
 
-PyObject * TVertex_setFrontSVertex( BPy_TVertex *self, PyObject *args) {
+static char TVertex_setFrontSVertex___doc__[] =
+".. method:: setFrontSVertex(iFrontSVertex)\n"
+"\n"
+"   Sets the SVertex that is closer to the viewpoint.\n"
+"\n"
+"   :arg iFrontSVertex: An SVertex object.\n"
+"   :type iFrontSVertex: :class:`SVertex`\n";
+
+static PyObject * TVertex_setFrontSVertex( BPy_TVertex *self, PyObject *args) {
 	PyObject *py_sv;
 
 	if(!( PyArg_ParseTuple(args, "O!", &SVertex_Type, &py_sv) ))
@@ -123,7 +97,15 @@ PyObject * TVertex_setFrontSVertex( BPy_TVertex *self, PyObject *args) {
 	Py_RETURN_NONE;
 }
 
-PyObject * TVertex_setBackSVertex( BPy_TVertex *self, PyObject *args) {
+static char TVertex_setBackSVertex___doc__[] =
+".. method:: setBackSVertex(iBackSVertex)\n"
+"\n"
+"   Sets the SVertex that is further away from the viewpoint.\n"
+"\n"
+"   :arg iBackSVertex: An SVertex object.\n"
+"   :type iBackSVertex: :class:`SVertex`\n";
+
+static PyObject * TVertex_setBackSVertex( BPy_TVertex *self, PyObject *args) {
 	PyObject *py_sv;
 
 	if(!( PyArg_ParseTuple(args, "O", &SVertex_Type, &py_sv) ))
@@ -134,7 +116,15 @@ PyObject * TVertex_setBackSVertex( BPy_TVertex *self, PyObject *args) {
 	Py_RETURN_NONE;
 }
 
-PyObject * TVertex_setId( BPy_TVertex *self, PyObject *args) {
+static char TVertex_setId___doc__[] =
+".. method:: setId(iId)\n"
+"\n"
+"   Sets the Id.\n"
+"\n"
+"   :arg iId: An Id object.\n"
+"   :type iId: :class:`Id`\n";
+
+static PyObject * TVertex_setId( BPy_TVertex *self, PyObject *args) {
 	PyObject *py_id;
 
 	if(!( PyArg_ParseTuple(args, "O!", &Id_Type, &py_id) ))
@@ -146,7 +136,17 @@ PyObject * TVertex_setId( BPy_TVertex *self, PyObject *args) {
 	Py_RETURN_NONE;
 }
 
-PyObject * TVertex_getSVertex( BPy_TVertex *self, PyObject *args) {
+static char TVertex_getSVertex___doc__[] =
+".. method:: getSVertex(iFEdge)\n"
+"\n"
+"   Returns the SVertex (among the 2) belonging to the given FEdge.\n"
+"\n"
+"   :arg iFEdge: An FEdge object.\n"
+"   :type iFEdge: :class:`FEdge`\n"
+"   :return: The SVertex belonging to the given FEdge.\n"
+"   :rtype: :class:`SVertex`\n";
+
+static PyObject * TVertex_getSVertex( BPy_TVertex *self, PyObject *args) {
 	PyObject *py_fe;
 
 	if(!( PyArg_ParseTuple(args, "O!", &FEdge_Type, &py_fe) ))
@@ -160,7 +160,19 @@ PyObject * TVertex_getSVertex( BPy_TVertex *self, PyObject *args) {
 	Py_RETURN_NONE;
 }
 
-PyObject * TVertex_mate( BPy_TVertex *self, PyObject *args) {
+static char TVertex_mate___doc__[] =
+".. method:: mate(iEdgeA)\n"
+"\n"
+"   Returns the mate edge of the ViewEdge given as argument.  If the\n"
+"   ViewEdge is frontEdgeA, frontEdgeB is returned.  If the ViewEdge is\n"
+"   frontEdgeB, frontEdgeA is returned.  Same for back edges.\n"
+"\n"
+"   :arg iEdgeA: A ViewEdge object.\n"
+"   :type iEdgeA: :class:`ViewEdge`\n"
+"   :return: The mate edge of the given ViewEdge.\n"
+"   :rtype: :class:`ViewEdge`\n";
+
+static PyObject * TVertex_mate( BPy_TVertex *self, PyObject *args) {
 	PyObject *py_ve;
 
 	if(!( PyArg_ParseTuple(args, "O!", &ViewEdge_Type, &py_ve) ))
@@ -174,7 +186,61 @@ PyObject * TVertex_mate( BPy_TVertex *self, PyObject *args) {
 	Py_RETURN_NONE;
 }
 
-	
+/*----------------------TVertex instance definitions ----------------------------*/
+static PyMethodDef BPy_TVertex_methods[] = {	
+//	{"__copy__", ( PyCFunction ) TVertex___copy__, METH_NOARGS, "() Cloning method."},
+	{"frontSVertex", ( PyCFunction ) TVertex_frontSVertex, METH_NOARGS, TVertex_frontSVertex___doc__},
+	{"backSVertex", ( PyCFunction ) TVertex_backSVertex, METH_NOARGS, TVertex_backSVertex___doc__},
+	{"setFrontSVertex", ( PyCFunction ) TVertex_setFrontSVertex, METH_VARARGS, TVertex_setFrontSVertex___doc__},
+	{"setBackSVertex", ( PyCFunction ) TVertex_setBackSVertex, METH_VARARGS, TVertex_setBackSVertex___doc__},
+	{"setId", ( PyCFunction ) TVertex_setId, METH_VARARGS, TVertex_setId___doc__},
+	{"getSVertex", ( PyCFunction ) TVertex_getSVertex, METH_VARARGS, TVertex_getSVertex___doc__},
+	{"mate", ( PyCFunction ) TVertex_mate, METH_VARARGS, TVertex_mate___doc__},
+	{NULL, NULL, 0, NULL}
+};
+
+/*-----------------------BPy_TVertex type definition ------------------------------*/
+PyTypeObject TVertex_Type = {
+	PyVarObject_HEAD_INIT(NULL, 0)
+	"TVertex",                      /* tp_name */
+	sizeof(BPy_TVertex),            /* 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 */
+	TVertex___doc__,                /* tp_doc */
+	0,                              /* tp_traverse */
+	0,                              /* tp_clear */
+	0,                              /* tp_richcompare */
+	0,                              /* tp_weaklistoffset */
+	0,                              /* tp_iter */
+	0,                              /* tp_iternext */
+	BPy_TVertex_methods,            /* tp_methods */
+	0,                              /* tp_members */
+	0,                              /* tp_getset */
+	&ViewVertex_Type,               /* tp_base */
+	0,                              /* tp_dict */
+	0,                              /* tp_descr_get */
+	0,                              /* tp_descr_set */
+	0,                              /* tp_dictoffset */
+	(initproc)TVertex___init__,     /* tp_init */
+	0,                              /* tp_alloc */
+	0,                              /* tp_new */
+};
+
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus