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, 155 insertions, 80 deletions

diff --git a/source/blender/freestyle/intern/python/Interface0D/BPy_SVertex.cpp b/source/blender/freestyle/intern/python/Interface0D/BPy_SVertex.cpp
index 84299ef3779..751955e1951 100644
--- a/source/blender/freestyle/intern/python/Interface0D/BPy_SVertex.cpp
+++ b/source/blender/freestyle/intern/python/Interface0D/BPy_SVertex.cpp
@@ -10,78 +10,32 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for SVertex instance  -----------*/
-static int SVertex___init__(BPy_SVertex *self, PyObject *args, PyObject *kwds);
-static PyObject * SVertex___copy__( BPy_SVertex *self );
-static PyObject * SVertex_normals( BPy_SVertex *self );
-static PyObject * SVertex_normalsSize( BPy_SVertex *self );
-static PyObject * SVertex_viewvertex( BPy_SVertex *self );
-static PyObject * SVertex_setPoint3D( BPy_SVertex *self , PyObject *args);
-static PyObject * SVertex_setPoint2D( BPy_SVertex *self , PyObject *args);
-static PyObject * SVertex_AddNormal( BPy_SVertex *self , PyObject *args);
-static PyObject * SVertex_setId( BPy_SVertex *self , PyObject *args);
-static PyObject *SVertex_AddFEdge( BPy_SVertex *self , PyObject *args);
-
-/*----------------------SVertex instance definitions ----------------------------*/
-static PyMethodDef BPy_SVertex_methods[] = {
-	{"__copy__", ( PyCFunction ) SVertex___copy__, METH_NOARGS, "() Cloning method."},
-	{"normals", ( PyCFunction ) SVertex_normals, METH_NOARGS, "Returns the normals for this Vertex as a list. In a smooth surface, a vertex has exactly one normal. In a sharp surface, a vertex can have any number of normals."},
-	{"normalsSize", ( PyCFunction ) SVertex_normalsSize, METH_NOARGS, "Returns the number of different normals for this vertex." },
-	{"viewvertex", ( PyCFunction ) SVertex_viewvertex, METH_NOARGS, "If this SVertex is also a ViewVertex, this method returns a pointer onto this ViewVertex. 0 is returned otherwise." },	
-	{"setPoint3D", ( PyCFunction ) SVertex_setPoint3D, METH_VARARGS, "Sets the 3D coordinates of the SVertex." },
-	{"setPoint2D", ( PyCFunction ) SVertex_setPoint2D, METH_VARARGS, "Sets the 3D projected coordinates of the SVertex." },
-	{"AddNormal", ( PyCFunction ) SVertex_AddNormal, METH_VARARGS, "Adds a normal to the Svertex's set of normals. If the same normal is already in the set, nothing changes." },
-	{"setId", ( PyCFunction ) SVertex_setId, METH_VARARGS, "Sets the Id." },
-	{"AddFEdge", ( PyCFunction ) SVertex_AddFEdge, METH_VARARGS, "Add an FEdge to the list of edges emanating from this SVertex." },	
-	{NULL, NULL, 0, NULL}
-};
-
-/*-----------------------BPy_SVertex type definition ------------------------------*/
-
-PyTypeObject SVertex_Type = {
-	PyVarObject_HEAD_INIT(NULL, 0)
-	"SVertex",                      /* tp_name */
-	sizeof(BPy_SVertex),            /* 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 */
-	"SVertex objects",              /* tp_doc */
-	0,                              /* tp_traverse */
-	0,                              /* tp_clear */
-	0,                              /* tp_richcompare */
-	0,                              /* tp_weaklistoffset */
-	0,                              /* tp_iter */
-	0,                              /* tp_iternext */
-	BPy_SVertex_methods,            /* tp_methods */
-	0,                              /* tp_members */
-	0,                              /* tp_getset */
-	&Interface0D_Type,              /* tp_base */
-	0,                              /* tp_dict */
-	0,                              /* tp_descr_get */
-	0,                              /* tp_descr_set */
-	0,                              /* tp_dictoffset */
-	(initproc)SVertex___init__,     /* tp_init */
-	0,                              /* tp_alloc */
-	0,                              /* tp_new */
-};
+static char SVertex___doc__[] =
+"Class to define a vertex of the embedding.\n"
+"\n"
+".. method:: __init__()\n"
+"\n"
+"   Default constructor.\n"
+"\n"
+".. method:: __init__(iBrother)\n"
+"\n"
+"   Copy constructor.\n"
+"\n"
+"   :arg iBrother: A SVertex object.\n"
+"   :type iBrother: :class:`SVertex`\n"
+"\n"
+".. method:: __init__(iPoint3D, id)\n"
+"\n"
+"   Builds a SVertex from 3D coordinates and an Id.\n"
+"\n"
+"   :arg iPoint3D: A three-dimensional vector.\n"
+"   :type iPoint3D: :class:`Mathutils.Vector`\n"
+"   :arg id: An Id object.\n"
+"   :type id: :class:`Id`\n";
 
 //------------------------INSTANCE METHODS ----------------------------------
 
-int SVertex___init__(BPy_SVertex *self, PyObject *args, PyObject *kwds)
+static int SVertex___init__(BPy_SVertex *self, PyObject *args, PyObject *kwds)
 {
 	PyObject *py_point = 0;
 	BPy_Id *py_id = 0;
@@ -116,7 +70,7 @@ int SVertex___init__(BPy_SVertex *self, PyObject *args, PyObject *kwds)
 	return 0;
 }
 
-PyObject * SVertex___copy__( BPy_SVertex *self ) {
+static PyObject * SVertex___copy__( BPy_SVertex *self ) {
 	BPy_SVertex *py_svertex;
 	
 	py_svertex = (BPy_SVertex *) SVertex_Type.tp_new( &SVertex_Type, 0, 0 );
@@ -128,8 +82,17 @@ PyObject * SVertex___copy__( BPy_SVertex *self ) {
 	return (PyObject *) py_svertex;
 }
 
-
-PyObject * SVertex_normals( BPy_SVertex *self ) {
+static char SVertex_normals___doc__[] =
+".. method:: normals()\n"
+"\n"
+"   Returns the normals for this Vertex as a list.  In a smooth surface,\n"
+"   a vertex has exactly one normal.  In a sharp surface, a vertex can\n"
+"   have any number of normals.\n"
+"\n"
+"   :return: A list of normals.\n"
+"   :rtype: List of :class:`Mathutils.Vector` objects\n";
+
+static PyObject * SVertex_normals( BPy_SVertex *self ) {
 	PyObject *py_normals; 
 	set< Vec3r > normals;
 	
@@ -144,11 +107,28 @@ PyObject * SVertex_normals( BPy_SVertex *self ) {
 	return py_normals;
 }
 
-PyObject * SVertex_normalsSize( BPy_SVertex *self ) {
+static char SVertex_normalsSize___doc__[] =
+".. method:: normalsSize()\n"
+"\n"
+"   Returns the number of different normals for this vertex.\n"
+"\n"
+"   :return: The number of normals.\n"
+"   :rtype: int\n";
+
+static PyObject * SVertex_normalsSize( BPy_SVertex *self ) {
 	return PyLong_FromLong( self->sv->normalsSize() );
 }
 
-PyObject * SVertex_viewvertex( BPy_SVertex *self ) {
+static char SVertex_viewvertex___doc__[] =
+".. method:: viewvertex()\n"
+"\n"
+"   If this SVertex is also a ViewVertex, this method returns the\n"
+"   ViewVertex.  None is returned otherwise.\n"
+"\n"
+"   :return: The ViewVertex object.\n"
+"   :rtype: :class:`ViewVertex`\n";
+
+static PyObject * SVertex_viewvertex( BPy_SVertex *self ) {
 	ViewVertex *vv = self->sv->viewvertex();
 	if( vv )
 		return Any_BPy_ViewVertex_from_ViewVertex( *vv );
@@ -156,7 +136,15 @@ PyObject * SVertex_viewvertex( BPy_SVertex *self ) {
 	Py_RETURN_NONE;
 }
 
-PyObject *SVertex_setPoint3D( BPy_SVertex *self , PyObject *args) {
+static char SVertex_setPoint3D___doc__[] =
+".. method:: setPoint3D(p)\n"
+"\n"
+"   Sets the 3D coordinates of the SVertex.\n"
+"\n"
+"   :arg p: A three-dimensional vector.\n"
+"   :type p: :class:`Mathutils.Vector`, list or tuple of 3 real numbers\n";
+
+static PyObject *SVertex_setPoint3D( BPy_SVertex *self , PyObject *args) {
 	PyObject *py_point;
 
 	if(!( PyArg_ParseTuple(args, "O", &py_point) ))
@@ -172,7 +160,15 @@ PyObject *SVertex_setPoint3D( BPy_SVertex *self , PyObject *args) {
 	Py_RETURN_NONE;
 }
 
-PyObject *SVertex_setPoint2D( BPy_SVertex *self , PyObject *args) {
+static char SVertex_setPoint2D___doc__[] =
+".. method:: setPoint2D(p)\n"
+"\n"
+"   Sets the 2D projected coordinates of the SVertex.\n"
+"\n"
+"   :arg p: A three-dimensional vector.\n"
+"   :type p: :class:`Mathutils.Vector`, list or tuple of 3 real numbers\n";
+
+static PyObject *SVertex_setPoint2D( BPy_SVertex *self , PyObject *args) {
 	PyObject *py_point;
 
 	if(!( PyArg_ParseTuple(args, "O", &py_point) ))
@@ -188,7 +184,16 @@ PyObject *SVertex_setPoint2D( BPy_SVertex *self , PyObject *args) {
 	Py_RETURN_NONE;
 }
 
-PyObject *SVertex_AddNormal( BPy_SVertex *self , PyObject *args) {
+static char SVertex_AddNormal___doc__[] =
+".. method:: AddNormal(n)\n"
+"\n"
+"   Adds a normal to the SVertex's set of normals.  If the same normal\n"
+"   is already in the set, nothing changes.\n"
+"\n"
+"   :arg n: A three-dimensional vector.\n"
+"   :type n: :class:`Mathutils.Vector`, list or tuple of 3 real numbers\n";
+
+static PyObject *SVertex_AddNormal( BPy_SVertex *self , PyObject *args) {
 	PyObject *py_normal;
 
 	if(!( PyArg_ParseTuple(args, "O", &py_normal) ))
@@ -204,7 +209,15 @@ PyObject *SVertex_AddNormal( BPy_SVertex *self , PyObject *args) {
 	Py_RETURN_NONE;
 }
 
-PyObject *SVertex_setId( BPy_SVertex *self , PyObject *args) {
+static char SVertex_setId___doc__[] =
+".. method:: setId(id)\n"
+"\n"
+"   Sets the identifier of the SVertex.\n"
+"\n"
+"   :arg id: The identifier.\n"
+"   :type id: :class:`Id`\n";
+
+static PyObject *SVertex_setId( BPy_SVertex *self , PyObject *args) {
 	BPy_Id *py_id;
 
 	if( !PyArg_ParseTuple(args, "O!", &Id_Type, &py_id) )
@@ -215,7 +228,15 @@ PyObject *SVertex_setId( BPy_SVertex *self , PyObject *args) {
 	Py_RETURN_NONE;
 }
 
-PyObject *SVertex_AddFEdge( BPy_SVertex *self , PyObject *args) {
+static char SVertex_AddFEdge___doc__[] =
+".. method:: AddFEdge(fe)\n"
+"\n"
+"   Add an FEdge to the list of edges emanating from this SVertex.\n"
+"\n"
+"   :arg fe: An FEdge.\n"
+"   :type fe: :class:`FEdge`\n";
+
+static PyObject *SVertex_AddFEdge( BPy_SVertex *self , PyObject *args) {
 	PyObject *py_fe;
 
 	if(!( PyArg_ParseTuple(args, "O!", &FEdge_Type, &py_fe) ))
@@ -226,10 +247,64 @@ PyObject *SVertex_AddFEdge( BPy_SVertex *self , PyObject *args) {
 	Py_RETURN_NONE;
 }
 
-
 // virtual bool 	operator== (const SVertex &iBrother)
 // ViewVertex * 	viewvertex ()
 
+/*----------------------SVertex instance definitions ----------------------------*/
+static PyMethodDef BPy_SVertex_methods[] = {
+	{"__copy__", ( PyCFunction ) SVertex___copy__, METH_NOARGS, "() Cloning method."},
+	{"normals", ( PyCFunction ) SVertex_normals, METH_NOARGS, SVertex_normals___doc__},
+	{"normalsSize", ( PyCFunction ) SVertex_normalsSize, METH_NOARGS, SVertex_normalsSize___doc__},
+	{"viewvertex", ( PyCFunction ) SVertex_viewvertex, METH_NOARGS, SVertex_viewvertex___doc__},
+	{"setPoint3D", ( PyCFunction ) SVertex_setPoint3D, METH_VARARGS, SVertex_setPoint3D___doc__},
+	{"setPoint2D", ( PyCFunction ) SVertex_setPoint2D, METH_VARARGS, SVertex_setPoint2D___doc__},
+	{"AddNormal", ( PyCFunction ) SVertex_AddNormal, METH_VARARGS, SVertex_AddNormal___doc__},
+	{"setId", ( PyCFunction ) SVertex_setId, METH_VARARGS, SVertex_setId___doc__},
+	{"AddFEdge", ( PyCFunction ) SVertex_AddFEdge, METH_VARARGS, SVertex_AddFEdge___doc__},
+	{NULL, NULL, 0, NULL}
+};
+
+/*-----------------------BPy_SVertex type definition ------------------------------*/
+PyTypeObject SVertex_Type = {
+	PyVarObject_HEAD_INIT(NULL, 0)
+	"SVertex",                      /* tp_name */
+	sizeof(BPy_SVertex),            /* 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 */
+	SVertex___doc__,                /* tp_doc */
+	0,                              /* tp_traverse */
+	0,                              /* tp_clear */
+	0,                              /* tp_richcompare */
+	0,                              /* tp_weaklistoffset */
+	0,                              /* tp_iter */
+	0,                              /* tp_iternext */
+	BPy_SVertex_methods,            /* tp_methods */
+	0,                              /* tp_members */
+	0,                              /* tp_getset */
+	&Interface0D_Type,              /* tp_base */
+	0,                              /* tp_dict */
+	0,                              /* tp_descr_get */
+	0,                              /* tp_descr_set */
+	0,                              /* tp_dictoffset */
+	(initproc)SVertex___init__,     /* tp_init */
+	0,                              /* tp_alloc */
+	0,                              /* tp_new */
+};
 
 ///////////////////////////////////////////////////////////////////////////////////////////