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, 186 insertions, 84 deletions

diff --git a/source/blender/freestyle/intern/python/Interface1D/FEdge/BPy_FEdgeSharp.cpp b/source/blender/freestyle/intern/python/Interface1D/FEdge/BPy_FEdgeSharp.cpp
index e699d843ed8..2c666534d66 100644
--- a/source/blender/freestyle/intern/python/Interface1D/FEdge/BPy_FEdgeSharp.cpp
+++ b/source/blender/freestyle/intern/python/Interface1D/FEdge/BPy_FEdgeSharp.cpp
@@ -9,81 +9,37 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for FEdgeSharp instance  -----------*/
-static int FEdgeSharp___init__(BPy_FEdgeSharp *self, PyObject *args, PyObject *kwds);
-
-static PyObject * FEdgeSharp_normalA( BPy_FEdgeSharp *self ) ;
-static PyObject * FEdgeSharp_normalB( BPy_FEdgeSharp *self );
-static PyObject * FEdgeSharp_aMaterialIndex( BPy_FEdgeSharp *self ) ;
-static PyObject * FEdgeSharp_bMaterialIndex( BPy_FEdgeSharp *self );
-static PyObject * FEdgeSharp_aMaterial( BPy_FEdgeSharp *self );
-static PyObject * FEdgeSharp_bMaterial( BPy_FEdgeSharp *self );
-static PyObject * FEdgeSharp_setNormalA( BPy_FEdgeSharp *self, PyObject *args );
-static PyObject * FEdgeSharp_setNormalB( BPy_FEdgeSharp *self, PyObject *args );
-static PyObject * FEdgeSharp_setaMaterialIndex( BPy_FEdgeSharp *self, PyObject *args );
-static PyObject * FEdgeSharp_setbMaterialIndex( BPy_FEdgeSharp *self, PyObject *args );
-
-/*----------------------FEdgeSharp instance definitions ----------------------------*/
-static PyMethodDef BPy_FEdgeSharp_methods[] = {	
-	{"normalA", ( PyCFunction ) FEdgeSharp_normalA, METH_NOARGS, "() Returns the normal to the face lying on the right of the FEdge. If this FEdge is a border, it has no Face on its right and therefore, no normal."},
-	{"normalB", ( PyCFunction ) FEdgeSharp_normalB, METH_NOARGS, "() Returns the normal to the face lying on the left of the FEdge."},
-	{"aMaterialIndex", ( PyCFunction ) FEdgeSharp_aMaterialIndex, METH_NOARGS, "() Returns the index of the material of the face lying on the right of the FEdge. If this FEdge is a border, it has no Face on its right and therefore, no material. "},
-	{"bMaterialIndex", ( PyCFunction ) FEdgeSharp_bMaterialIndex, METH_NOARGS, "() Returns the material of the face lying on the left of the FEdge. "},
-	{"aMaterial", ( PyCFunction ) FEdgeSharp_aMaterial, METH_NOARGS, "() Returns the material of the face lying on the right of the FEdge. If this FEdge is a border, it has no Face on its right and therefore, no material."},
-	{"bMaterial", ( PyCFunction ) FEdgeSharp_bMaterial, METH_NOARGS, "() Returns the material of the face lying on the left of the FEdge."},
-	{"setNormalA", ( PyCFunction ) FEdgeSharp_setNormalA, METH_VARARGS, "([x,y,z]) Sets the normal to the face lying on the right of the FEdge."},
-	{"setNormalB", ( PyCFunction ) FEdgeSharp_setNormalB, METH_VARARGS, "([x,y,z]) Sets the normal to the face lying on the left of the FEdge. "},
-	{"setaMaterialIndex", ( PyCFunction ) FEdgeSharp_setaMaterialIndex, METH_VARARGS, "(unsigned int i) Sets the index of the material lying on the right of the FEdge. "},
-	{"setbMaterialIndex", ( PyCFunction ) FEdgeSharp_setbMaterialIndex, METH_VARARGS, "(unsigned int i) Sets the index of the material lying on the left of the FEdge. "},
-	{NULL, NULL, 0, NULL}
-};
-
-/*-----------------------BPy_FEdgeSharp type definition ------------------------------*/
-
-PyTypeObject FEdgeSharp_Type = {
-	PyVarObject_HEAD_INIT(NULL, 0)
-	"FEdgeSharp",                   /* tp_name */
-	sizeof(BPy_FEdgeSharp),         /* 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 */
-	"FEdgeSharp objects",           /* tp_doc */
-	0,                              /* tp_traverse */
-	0,                              /* tp_clear */
-	0,                              /* tp_richcompare */
-	0,                              /* tp_weaklistoffset */
-	0,                              /* tp_iter */
-	0,                              /* tp_iternext */
-	BPy_FEdgeSharp_methods,         /* tp_methods */
-	0,                              /* tp_members */
-	0,                              /* tp_getset */
-	&FEdge_Type,                    /* tp_base */
-	0,                              /* tp_dict */
-	0,                              /* tp_descr_get */
-	0,                              /* tp_descr_set */
-	0,                              /* tp_dictoffset */
-	(initproc)FEdgeSharp___init__,  /* tp_init */
-	0,                              /* tp_alloc */
-	0,                              /* tp_new */
-};
-
 //------------------------INSTANCE METHODS ----------------------------------
 
-int FEdgeSharp___init__(BPy_FEdgeSharp *self, PyObject *args, PyObject *kwds)
+static char FEdgeSharp___doc__[] =
+"Class defining a sharp FEdge.  A Sharp FEdge corresponds to an initial\n"
+"edge of the input mesh.  It can be a silhouette, a crease or a border.\n"
+"If it is a crease edge, then it is borded by two faces of the mesh.\n"
+"Face a lies on its right whereas Face b lies on its left.  If it is a\n"
+"border edge, then it doesn't have any face on its right, and thus Face\n"
+"a is None.\n"
+"\n"
+".. method:: __init__()\n"
+"\n"
+"   Default constructor.\n"
+"\n"
+".. method:: __init__(iBrother)\n"
+"\n"
+"   Copy constructor.\n"
+"\n"
+"   :arg iBrother: An FEdgeSharp object.\n"
+"   :type iBrother: :class:`FEdgeSharp`\n"
+"\n"
+".. method:: __init__(vA, vB)\n"
+"\n"
+"   Builds an FEdgeSharp going from vA to vB.\n"
+"\n"
+"   :arg vA: The first SVertex object.\n"
+"   :type vA: :class:`SVertex`\n"
+"   :arg vB: The second SVertex object.\n"
+"   :type vB: :class:`SVertex`\n";
+
+static int FEdgeSharp___init__(BPy_FEdgeSharp *self, PyObject *args, PyObject *kwds)
 {
 	PyObject *obj1 = 0, *obj2 = 0;
 
@@ -111,36 +67,100 @@ int FEdgeSharp___init__(BPy_FEdgeSharp *self, PyObject *args, PyObject *kwds)
 	return 0;
 }
 
-
-PyObject * FEdgeSharp_normalA( BPy_FEdgeSharp *self ) {
+static char FEdgeSharp_normalA___doc__[] =
+".. method:: normalA()\n"
+"\n"
+"   Returns the normal to the face lying on the right of the FEdge.  If\n"
+"   this FEdge is a border, it has no Face on its right and therefore, no\n"
+"   normal.\n"
+"\n"
+"   :return: The normal to the face lying on the right of the FEdge.\n"
+"   :rtype: :class:`Mathutils.Vector`\n";
+
+static PyObject * FEdgeSharp_normalA( BPy_FEdgeSharp *self ) {
 	Vec3r v( self->fes->normalA() );
 	return Vector_from_Vec3r( v );
 }
 
-PyObject * FEdgeSharp_normalB( BPy_FEdgeSharp *self ) {
+static char FEdgeSharp_normalB___doc__[] =
+".. method:: normalB()\n"
+"\n"
+"   Returns the normal to the face lying on the left of the FEdge.\n"
+"\n"
+"   :return: The normal to the face lying on the left of the FEdge.\n"
+"   :rtype: :class:`Mathutils.Vector`\n";
+
+static PyObject * FEdgeSharp_normalB( BPy_FEdgeSharp *self ) {
 	Vec3r v( self->fes->normalB() );
 	return Vector_from_Vec3r( v );
 }
 
-PyObject * FEdgeSharp_aMaterialIndex( BPy_FEdgeSharp *self ) {
+static char FEdgeSharp_aMaterialIndex___doc__[] =
+".. method:: aMaterialIndex()\n"
+"\n"
+"   Returns the index of the material of the face lying on the right of\n"
+"   the FEdge. If this FEdge is a border, it has no Face on its right and\n"
+"   therefore, no material.\n"
+"\n"
+"   :return: The index of the material of the face lying on the right of\n"
+"      the FEdge.\n"
+"   :rtype: int\n";
+
+static PyObject * FEdgeSharp_aMaterialIndex( BPy_FEdgeSharp *self ) {
 	return PyLong_FromLong( self->fes->aFrsMaterialIndex() );
 }
 
-PyObject * FEdgeSharp_bMaterialIndex( BPy_FEdgeSharp *self ) {
+static char FEdgeSharp_bMaterialIndex___doc__[] =
+".. method:: bMaterialIndex()\n"
+"\n"
+"   Returns the index of the material of the face lying on the left of\n"
+"   the FEdge.\n"
+"\n"
+"   :return: The index of the material of the face lying on the left of\n"
+"      the FEdge.\n"
+"   :rtype: int\n";
+
+static PyObject * FEdgeSharp_bMaterialIndex( BPy_FEdgeSharp *self ) {
 	return PyLong_FromLong( self->fes->bFrsMaterialIndex() );
 }
 
-PyObject * FEdgeSharp_aMaterial( BPy_FEdgeSharp *self ) {
+static char FEdgeSharp_aMaterial___doc__[] =
+".. method:: aMaterial()\n"
+"\n"
+"   Returns the material of the face lying on the right of the FEdge.  If\n"
+"   this FEdge is a border, it has no Face on its right and therefore, no\n"
+"   material.\n"
+"\n"
+"   :return: The material of the face lying on the right of the FEdge.\n"
+"   :rtype: :class:`Material`\n";
+
+static PyObject * FEdgeSharp_aMaterial( BPy_FEdgeSharp *self ) {
 	FrsMaterial m( self->fes->aFrsMaterial() );
 	return BPy_FrsMaterial_from_FrsMaterial(m);
 }
 
-PyObject * FEdgeSharp_bMaterial( BPy_FEdgeSharp *self ) {
+static char FEdgeSharp_bMaterial___doc__[] =
+".. method:: bMaterial()\n"
+"\n"
+"   Returns the material of the face lying on the left of the FEdge.\n"
+"\n"
+"   :return: The material of the face lying on the left of the FEdge.\n"
+"   :rtype: :class:`Material`\n";
+
+static PyObject * FEdgeSharp_bMaterial( BPy_FEdgeSharp *self ) {
 	FrsMaterial m( self->fes->aFrsMaterial() );
 	return BPy_FrsMaterial_from_FrsMaterial(m);
 }
 
-PyObject * FEdgeSharp_setNormalA( BPy_FEdgeSharp *self, PyObject *args ) {
+static char FEdgeSharp_setNormalA___doc__[] =
+".. method:: setNormalA(iNormal)\n"
+"\n"
+"   Sets the normal to the face lying on the right of the FEdge.\n"
+"\n"
+"   :arg iNormal: A three-dimensional vector.\n"
+"   :type iNormal: :class:`Mathutils.Vector`, list or tuple of 3 real numbers\n";
+
+static PyObject * FEdgeSharp_setNormalA( BPy_FEdgeSharp *self, PyObject *args ) {
 	PyObject *obj = 0;
 
 	if(!( PyArg_ParseTuple(args, "O", &obj) ))
@@ -156,7 +176,15 @@ PyObject * FEdgeSharp_setNormalA( BPy_FEdgeSharp *self, PyObject *args ) {
 	Py_RETURN_NONE;
 }
 
-PyObject * FEdgeSharp_setNormalB( BPy_FEdgeSharp *self, PyObject *args ) {
+static char FEdgeSharp_setNormalB___doc__[] =
+".. method:: setNormalB(iNormal)\n"
+"\n"
+"   Sets the normal to the face lying on the left of the FEdge.\n"
+"\n"
+"   :arg iNormal: A three-dimensional vector.\n"
+"   :type iNormal: :class:`Mathutils.Vector`, list or tuple of 3 real numbers\n";
+
+static PyObject * FEdgeSharp_setNormalB( BPy_FEdgeSharp *self, PyObject *args ) {
 	PyObject *obj = 0;
 
 	if(!( PyArg_ParseTuple(args, "O", &obj) ))
@@ -172,7 +200,15 @@ PyObject * FEdgeSharp_setNormalB( BPy_FEdgeSharp *self, PyObject *args ) {
 	Py_RETURN_NONE;
 }
 
-PyObject * FEdgeSharp_setaMaterialIndex( BPy_FEdgeSharp *self, PyObject *args ) {
+static char FEdgeSharp_setaMaterialIndex___doc__[] =
+".. method:: setaMaterialIndex(i)\n"
+"\n"
+"   Sets the index of the material lying on the right of the FEdge.\n"
+"\n"
+"   :arg i: A material index.\n"
+"   :type i: int\n";
+
+static PyObject * FEdgeSharp_setaMaterialIndex( BPy_FEdgeSharp *self, PyObject *args ) {
 	unsigned int i;
 
 	if(!( PyArg_ParseTuple(args, "I", &i) ))
@@ -183,7 +219,15 @@ PyObject * FEdgeSharp_setaMaterialIndex( BPy_FEdgeSharp *self, PyObject *args )
 	Py_RETURN_NONE;
 }
 
-PyObject * FEdgeSharp_setbMaterialIndex( BPy_FEdgeSharp *self, PyObject *args ) {
+static char FEdgeSharp_setbMaterialIndex___doc__[] =
+".. method:: setbMaterialIndex(i)\n"
+"\n"
+"   Sets the index of the material lying on the left of the FEdge.\n"
+"\n"
+"   :arg i: A material index.\n"
+"   :type i: int\n";
+
+static PyObject * FEdgeSharp_setbMaterialIndex( BPy_FEdgeSharp *self, PyObject *args ) {
 	unsigned int i;
 
 	if(!( PyArg_ParseTuple(args, "I", &i) ))
@@ -194,6 +238,64 @@ PyObject * FEdgeSharp_setbMaterialIndex( BPy_FEdgeSharp *self, PyObject *args )
 	Py_RETURN_NONE;
 }
 
+/*----------------------FEdgeSharp instance definitions ----------------------------*/
+static PyMethodDef BPy_FEdgeSharp_methods[] = {	
+	{"normalA", ( PyCFunction ) FEdgeSharp_normalA, METH_NOARGS, FEdgeSharp_normalA___doc__},
+	{"normalB", ( PyCFunction ) FEdgeSharp_normalB, METH_NOARGS, FEdgeSharp_normalB___doc__},
+	{"aMaterialIndex", ( PyCFunction ) FEdgeSharp_aMaterialIndex, METH_NOARGS, FEdgeSharp_aMaterialIndex___doc__},
+	{"bMaterialIndex", ( PyCFunction ) FEdgeSharp_bMaterialIndex, METH_NOARGS, FEdgeSharp_bMaterialIndex___doc__},
+	{"aMaterial", ( PyCFunction ) FEdgeSharp_aMaterial, METH_NOARGS, FEdgeSharp_aMaterial___doc__},
+	{"bMaterial", ( PyCFunction ) FEdgeSharp_bMaterial, METH_NOARGS, FEdgeSharp_bMaterial___doc__},
+	{"setNormalA", ( PyCFunction ) FEdgeSharp_setNormalA, METH_VARARGS, FEdgeSharp_setNormalA___doc__},
+	{"setNormalB", ( PyCFunction ) FEdgeSharp_setNormalB, METH_VARARGS, FEdgeSharp_setNormalB___doc__},
+	{"setaMaterialIndex", ( PyCFunction ) FEdgeSharp_setaMaterialIndex, METH_VARARGS, FEdgeSharp_setaMaterialIndex___doc__},
+	{"setbMaterialIndex", ( PyCFunction ) FEdgeSharp_setbMaterialIndex, METH_VARARGS, FEdgeSharp_setbMaterialIndex___doc__},
+	{NULL, NULL, 0, NULL}
+};
+
+/*-----------------------BPy_FEdgeSharp type definition ------------------------------*/
+
+PyTypeObject FEdgeSharp_Type = {
+	PyVarObject_HEAD_INIT(NULL, 0)
+	"FEdgeSharp",                   /* tp_name */
+	sizeof(BPy_FEdgeSharp),         /* 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 */
+	FEdgeSharp___doc__,             /* tp_doc */
+	0,                              /* tp_traverse */
+	0,                              /* tp_clear */
+	0,                              /* tp_richcompare */
+	0,                              /* tp_weaklistoffset */
+	0,                              /* tp_iter */
+	0,                              /* tp_iternext */
+	BPy_FEdgeSharp_methods,         /* tp_methods */
+	0,                              /* tp_members */
+	0,                              /* tp_getset */
+	&FEdge_Type,                    /* tp_base */
+	0,                              /* tp_dict */
+	0,                              /* tp_descr_get */
+	0,                              /* tp_descr_set */
+	0,                              /* tp_dictoffset */
+	(initproc)FEdgeSharp___init__,  /* tp_init */
+	0,                              /* tp_alloc */
+	0,                              /* tp_new */
+};
+
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus