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, 164 insertions, 77 deletions

diff --git a/source/blender/freestyle/intern/python/Interface0D/BPy_CurvePoint.cpp b/source/blender/freestyle/intern/python/Interface0D/BPy_CurvePoint.cpp
index 48aa1e5aa1c..35f8c82f794 100644
--- a/source/blender/freestyle/intern/python/Interface0D/BPy_CurvePoint.cpp
+++ b/source/blender/freestyle/intern/python/Interface0D/BPy_CurvePoint.cpp
@@ -9,76 +9,55 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for CurvePoint instance  -----------*/
-static int CurvePoint___init__(BPy_CurvePoint *self, PyObject *args, PyObject *kwds);
-static PyObject * CurvePoint___copy__( BPy_CurvePoint *self );
-static PyObject * CurvePoint_A( BPy_CurvePoint *self );
-static PyObject * CurvePoint_B( BPy_CurvePoint *self );
-static PyObject * CurvePoint_t2d( BPy_CurvePoint *self );
-static PyObject *CurvePoint_setA( BPy_CurvePoint *self , PyObject *args);
-static PyObject *CurvePoint_setB( BPy_CurvePoint *self , PyObject *args);
-static PyObject *CurvePoint_setT2d( BPy_CurvePoint *self , PyObject *args);
-static PyObject *CurvePoint_curvatureFredo( BPy_CurvePoint *self , PyObject *args);
-
-/*----------------------CurvePoint instance definitions ----------------------------*/
-static PyMethodDef BPy_CurvePoint_methods[] = {	
-	{"__copy__", ( PyCFunction ) CurvePoint___copy__, METH_NOARGS, "() Cloning method."},
-	{"A", ( PyCFunction ) CurvePoint_A, METH_NOARGS, "() Returns the first SVertex upon which the CurvePoint is built."},
-	{"B", ( PyCFunction ) CurvePoint_B, METH_NOARGS, "() Returns the second SVertex upon which the CurvePoint is built."},
-	{"t2d", ( PyCFunction ) CurvePoint_t2d, METH_NOARGS, "() Returns the interpolation parameter."},
-	{"setA", ( PyCFunction ) CurvePoint_setA, METH_VARARGS, "(SVertex sv) Sets the first SVertex upon which to build the CurvePoint."},
-	{"setB", ( PyCFunction ) CurvePoint_setB, METH_VARARGS, "(SVertex sv) Sets the second SVertex upon which to build the CurvePoint."},
-	{"setT2d", ( PyCFunction ) CurvePoint_setT2d, METH_VARARGS, "() Sets the 2D interpolation parameter to use."},
-	{"curvatureFredo", ( PyCFunction ) CurvePoint_curvatureFredo, METH_NOARGS, "() angle in radians."},
-	{NULL, NULL, 0, NULL}
-};
-
-/*-----------------------BPy_CurvePoint type definition ------------------------------*/
-
-PyTypeObject CurvePoint_Type = {
-	PyVarObject_HEAD_INIT(NULL, 0)
-	"CurvePoint",                   /* tp_name */
-	sizeof(BPy_CurvePoint),         /* 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 */
-	"CurvePoint objects",           /* tp_doc */
-	0,                              /* tp_traverse */
-	0,                              /* tp_clear */
-	0,                              /* tp_richcompare */
-	0,                              /* tp_weaklistoffset */
-	0,                              /* tp_iter */
-	0,                              /* tp_iternext */
-	BPy_CurvePoint_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)CurvePoint___init__,  /* tp_init */
-	0,                              /* tp_alloc */
-	0,                              /* tp_new */
-};
-
 //------------------------INSTANCE METHODS ----------------------------------
 
-int CurvePoint___init__(BPy_CurvePoint *self, PyObject *args, PyObject *kwds)
+static char CurvePoint___doc__[] =
+"Class to represent a point of a curve.  A CurvePoint can be any point\n"
+"of a 1D curve (it doesn't have to be a vertex of the curve).  Any\n"
+":class:`Interface1D` is built upon ViewEdges, themselves built upon\n"
+"FEdges.  Therefore, a curve is basically a polyline made of a list of\n"
+":class:`SVertex` objects.  Thus, a CurvePoint is built by linearly\n"
+"interpolating two :class:`SVertex` instances.  CurvePoint can be used\n"
+"as virtual points while querying 0D information along a curve at a\n"
+"given resolution.\n"
+"\n"
+".. method:: __init__()\n"
+"\n"
+"   Defult constructor.\n"
+"\n"
+".. method:: __init__(iBrother)\n"
+"\n"
+"   Copy constructor.\n"
+"\n"
+"   :arg iBrother: A CurvePoint object.\n"
+"   :type iBrother: :class:`CurvePoint`\n"
+"\n"
+".. method:: __init__(iA, iB, t2d)\n"
+"\n"
+"   Builds a CurvePoint from two SVertex and an interpolation parameter.\n"
+"\n"
+"   :arg iA: The first SVertex.\n"
+"   :type iA: :class:`SVertex`\n"
+"   :arg iB: The second SVertex.\n"
+"   :type iB: :class:`SVertex`\n"
+"   :arg t2d: A 2D interpolation parameter used to linearly interpolate\n"
+"             iA and iB.\n"
+"   :type t2d: float\n"
+"\n"
+".. method:: __init__(iA, iB, t2d)\n"
+"\n"
+"   Builds a CurvePoint from two CurvePoint and an interpolation\n"
+"   parameter.\n"
+"\n"
+"   :arg iA: The first CurvePoint.\n"
+"   :type iA: :class:`CurvePoint`\n"
+"   :arg iB: The second CurvePoint.\n"
+"   :type iB: :class:`CurvePoint`\n"
+"   :arg t2d: The 2D interpolation parameter used to linearly\n"
+"             interpolate iA and iB.\n"
+"   :type t2d: float\n";
+
+static int CurvePoint___init__(BPy_CurvePoint *self, PyObject *args, PyObject *kwds)
 {
 
 	PyObject *obj1 = 0, *obj2 = 0 , *obj3 = 0;
@@ -121,7 +100,7 @@ int CurvePoint___init__(BPy_CurvePoint *self, PyObject *args, PyObject *kwds)
 	return 0;
 }
 
-PyObject * CurvePoint___copy__( BPy_CurvePoint *self ) {
+static PyObject * CurvePoint___copy__( BPy_CurvePoint *self ) {
 	BPy_CurvePoint *py_cp;
 	
 	py_cp = (BPy_CurvePoint *) CurvePoint_Type.tp_new( &CurvePoint_Type, 0, 0 );
@@ -133,7 +112,15 @@ PyObject * CurvePoint___copy__( BPy_CurvePoint *self ) {
 	return (PyObject *) py_cp;
 }
 
-PyObject * CurvePoint_A( BPy_CurvePoint *self ) {
+static char CurvePoint_A___doc__[] =
+".. method:: A()\n"
+"\n"
+"   Returns the first SVertex upon which the CurvePoint is built.\n"
+"\n"
+"   :return: The first SVertex.\n"
+"   :rtype: :class:`SVertex`\n";
+
+static PyObject * CurvePoint_A( BPy_CurvePoint *self ) {
 	SVertex *A = self->cp->A();
 	if( A )
 		return BPy_SVertex_from_SVertex( *A );
@@ -141,7 +128,15 @@ PyObject * CurvePoint_A( BPy_CurvePoint *self ) {
 	Py_RETURN_NONE;
 }
 
-PyObject * CurvePoint_B( BPy_CurvePoint *self ) {
+static char CurvePoint_B___doc__[] =
+".. method:: B()\n"
+"\n"
+"   Returns the second SVertex upon which the CurvePoint is built.\n"
+"\n"
+"   :return: The second SVertex.\n"
+"   :rtype: :class:`SVertex`\n";
+
+static PyObject * CurvePoint_B( BPy_CurvePoint *self ) {
 	SVertex *B = self->cp->B();
 	if( B )
 		return BPy_SVertex_from_SVertex( *B );
@@ -149,11 +144,27 @@ PyObject * CurvePoint_B( BPy_CurvePoint *self ) {
 	Py_RETURN_NONE;
 }
 
-PyObject * CurvePoint_t2d( BPy_CurvePoint *self ) {
+static char CurvePoint_t2d___doc__[] =
+".. method:: t2d()\n"
+"\n"
+"   Returns the 2D interpolation parameter.\n"
+"\n"
+"   :return: The 2D interpolation parameter.\n"
+"   :rtype: float\n";
+
+static PyObject * CurvePoint_t2d( BPy_CurvePoint *self ) {
 	return PyFloat_FromDouble( self->cp->t2d() );
 }
 
-PyObject *CurvePoint_setA( BPy_CurvePoint *self , PyObject *args) {
+static char CurvePoint_setA___doc__[] =
+".. method:: setA(iA)\n"
+"\n"
+"   Sets the first SVertex upon which to build the CurvePoint.\n"
+"\n"
+"   :arg iA: The first SVertex.\n"
+"   :type iA: :class:`SVertex`\n";
+
+static PyObject *CurvePoint_setA( BPy_CurvePoint *self , PyObject *args) {
 	PyObject *py_sv;
 
 	if(!( PyArg_ParseTuple(args, "O!", &SVertex_Type, &py_sv) ))
@@ -164,7 +175,15 @@ PyObject *CurvePoint_setA( BPy_CurvePoint *self , PyObject *args) {
 	Py_RETURN_NONE;
 }
 
-PyObject *CurvePoint_setB( BPy_CurvePoint *self , PyObject *args) {
+static char CurvePoint_setB___doc__[] =
+".. method:: setB(iB)\n"
+"\n"
+"   Sets the first SVertex upon which to build the CurvePoint.\n"
+"\n"
+"   :arg iB: The second SVertex.\n"
+"   :type iB: :class:`SVertex`\n";
+
+static PyObject *CurvePoint_setB( BPy_CurvePoint *self , PyObject *args) {
 	PyObject *py_sv;
 
 	if(!( PyArg_ParseTuple(args, "O!", &SVertex_Type, &py_sv) ))
@@ -175,7 +194,15 @@ PyObject *CurvePoint_setB( BPy_CurvePoint *self , PyObject *args) {
 	Py_RETURN_NONE;
 }
 
-PyObject *CurvePoint_setT2d( BPy_CurvePoint *self , PyObject *args) {
+static char CurvePoint_setT2d___doc__[] =
+".. method:: setT2d(t)\n"
+"\n"
+"   Sets the 2D interpolation parameter to use.\n"
+"\n"
+"   :arg t: The 2D interpolation parameter.\n"
+"   :type t: float\n";
+
+static PyObject *CurvePoint_setT2d( BPy_CurvePoint *self , PyObject *args) {
 	float t;
 
 	if(!( PyArg_ParseTuple(args, "f", &t) ))
@@ -186,14 +213,74 @@ PyObject *CurvePoint_setT2d( BPy_CurvePoint *self , PyObject *args) {
 	Py_RETURN_NONE;
 }
 
-PyObject *CurvePoint_curvatureFredo( BPy_CurvePoint *self , PyObject *args) {
+static char CurvePoint_curvatureFredo___doc__[] =
+".. method:: curvatureFredo()\n"
+"\n"
+"   Returns the angle in radians.\n"
+"\n"
+"   :return: The angle in radians.\n"
+"   :rtype: float\n";
+
+static PyObject *CurvePoint_curvatureFredo( BPy_CurvePoint *self , PyObject *args) {
 	return PyFloat_FromDouble( self->cp->curvatureFredo() );
 }
 
 ///bool 	operator== (const CurvePoint &b)
 
+/*----------------------CurvePoint instance definitions ----------------------------*/
+static PyMethodDef BPy_CurvePoint_methods[] = {	
+	{"__copy__", ( PyCFunction ) CurvePoint___copy__, METH_NOARGS, "() Cloning method."},
+	{"A", ( PyCFunction ) CurvePoint_A, METH_NOARGS, CurvePoint_A___doc__},
+	{"B", ( PyCFunction ) CurvePoint_B, METH_NOARGS, CurvePoint_B___doc__},
+	{"t2d", ( PyCFunction ) CurvePoint_t2d, METH_NOARGS, CurvePoint_t2d___doc__},
+	{"setA", ( PyCFunction ) CurvePoint_setA, METH_VARARGS, CurvePoint_setA___doc__},
+	{"setB", ( PyCFunction ) CurvePoint_setB, METH_VARARGS, CurvePoint_setB___doc__},
+	{"setT2d", ( PyCFunction ) CurvePoint_setT2d, METH_VARARGS, CurvePoint_setT2d___doc__},
+	{"curvatureFredo", ( PyCFunction ) CurvePoint_curvatureFredo, METH_NOARGS, CurvePoint_curvatureFredo___doc__},
+	{NULL, NULL, 0, NULL}
+};
 
-
+/*-----------------------BPy_CurvePoint type definition ------------------------------*/
+PyTypeObject CurvePoint_Type = {
+	PyVarObject_HEAD_INIT(NULL, 0)
+	"CurvePoint",                   /* tp_name */
+	sizeof(BPy_CurvePoint),         /* 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 */
+	CurvePoint___doc__,             /* tp_doc */
+	0,                              /* tp_traverse */
+	0,                              /* tp_clear */
+	0,                              /* tp_richcompare */
+	0,                              /* tp_weaklistoffset */
+	0,                              /* tp_iter */
+	0,                              /* tp_iternext */
+	BPy_CurvePoint_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)CurvePoint___init__,  /* tp_init */
+	0,                              /* tp_alloc */
+	0,                              /* tp_new */
+};
 
 ///////////////////////////////////////////////////////////////////////////////////////////