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, 113 insertions, 65 deletions

diff --git a/source/blender/freestyle/intern/python/Interface1D/BPy_FrsCurve.cpp b/source/blender/freestyle/intern/python/Interface1D/BPy_FrsCurve.cpp
index ef9cd8bfebd..1ec9e3efc53 100644
--- a/source/blender/freestyle/intern/python/Interface1D/BPy_FrsCurve.cpp
+++ b/source/blender/freestyle/intern/python/Interface1D/BPy_FrsCurve.cpp
@@ -11,68 +11,32 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for FrsCurve instance  -----------*/
-static int FrsCurve___init__(BPy_FrsCurve *self, PyObject *args, PyObject *kwds);
-static PyObject * FrsCurve_push_vertex_back( BPy_FrsCurve *self, PyObject *args );
-static PyObject * FrsCurve_push_vertex_front( BPy_FrsCurve *self, PyObject *args );
-static PyObject * FrsCurve_empty( BPy_FrsCurve *self );
-static PyObject * FrsCurve_nSegments( BPy_FrsCurve *self );
-
-/*----------------------FrsCurve instance definitions ----------------------------*/
-static PyMethodDef BPy_FrsCurve_methods[] = {	
-	{"push_vertex_back", ( PyCFunction ) FrsCurve_push_vertex_back, METH_VARARGS, "(CurvePoint cp | SVertex sv) Adds a single vertex at the front of the Curve."},
-	{"push_vertex_front", ( PyCFunction ) FrsCurve_push_vertex_front, METH_VARARGS, "(CurvePoint cp | SVertex sv) Adds a single vertex at the end of the Curve."},
-	{"empty", ( PyCFunction ) FrsCurve_empty, METH_NOARGS, "() Returns true is the Curve doesn't have any Vertex yet."},
-	{"nSegments", ( PyCFunction ) FrsCurve_nSegments, METH_NOARGS, "() Returns the number of segments in the oplyline constituing the Curve."},
-	{NULL, NULL, 0, NULL}
-};
-
-/*-----------------------BPy_FrsCurve type definition ------------------------------*/
-
-PyTypeObject FrsCurve_Type = {
-	PyVarObject_HEAD_INIT(NULL, 0)
-	"FrsCurve",                     /* tp_name */
-	sizeof(BPy_FrsCurve),           /* 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 */
-	"FrsCurve objects",             /* tp_doc */
-	0,                              /* tp_traverse */
-	0,                              /* tp_clear */
-	0,                              /* tp_richcompare */
-	0,                              /* tp_weaklistoffset */
-	0,                              /* tp_iter */
-	0,                              /* tp_iternext */
-	BPy_FrsCurve_methods,           /* tp_methods */
-	0,                              /* tp_members */
-	0,                              /* tp_getset */
-	&Interface1D_Type,              /* tp_base */
-	0,                              /* tp_dict */
-	0,                              /* tp_descr_get */
-	0,                              /* tp_descr_set */
-	0,                              /* tp_dictoffset */
-	(initproc)FrsCurve___init__,    /* tp_init */
-	0,                              /* tp_alloc */
-	0,                              /* tp_new */
-};
-
 //------------------------INSTANCE METHODS ----------------------------------
-	
-int FrsCurve___init__(BPy_FrsCurve *self, PyObject *args, PyObject *kwds)
+
+static char FrsCurve___doc__[] =
+"Base class for curves made of CurvePoints.  :class:`SVertex` is the\n"
+"type of the initial curve vertices.  A :class:`Chain` is a\n"
+"specialization of a Curve.\n"
+"\n"
+".. method:: __init__()\n"
+"\n"
+"   Default Constructor.\n"
+"\n"
+".. method:: __init__(iBrother)\n"
+"\n"
+"   Copy Constructor.\n"
+"\n"
+"   :arg iBrother: A FrsCurve object.\n"
+"   :type iBrother: :class:`FrsCurve`\n"
+"\n"
+".. method:: __init__(iId)\n"
+"\n"
+"   Builds a FrsCurve from its Id.\n"
+"\n"
+"   :arg iId: An Id object.\n"
+"   :type iId: :class:`Id`\n";
+
+static int FrsCurve___init__(BPy_FrsCurve *self, PyObject *args, PyObject *kwds)
 {
 
 	PyObject *obj = 0;
@@ -100,8 +64,15 @@ int FrsCurve___init__(BPy_FrsCurve *self, PyObject *args, PyObject *kwds)
 	return 0;
 }
 
+static char FrsCurve_push_vertex_back___doc__[] =
+".. method:: push_vertex_back(iVertex)\n"
+"\n"
+"   Adds a single vertex at the end of the FrsCurve.\n"
+"\n"
+"   :arg iVertex: A vertex object.\n"
+"   :type iVertex: :class:`SVertex` or :class:`CurvePoint`\n";
 
-PyObject * FrsCurve_push_vertex_back( BPy_FrsCurve *self, PyObject *args ) {
+static PyObject * FrsCurve_push_vertex_back( BPy_FrsCurve *self, PyObject *args ) {
 	PyObject *obj;
 
 	if(!( PyArg_ParseTuple(args, "O", &obj) ))
@@ -119,7 +90,15 @@ PyObject * FrsCurve_push_vertex_back( BPy_FrsCurve *self, PyObject *args ) {
 	Py_RETURN_NONE;
 }
 
-PyObject * FrsCurve_push_vertex_front( BPy_FrsCurve *self, PyObject *args ) {
+static char FrsCurve_push_vertex_front___doc__[] =
+".. method:: push_vertex_front(iVertex)\n"
+"\n"
+"   Adds a single vertex at the front of the FrsCurve.\n"
+"\n"
+"   :arg iVertex: A vertex object.\n"
+"   :type iVertex: :class:`SVertex` or :class:`CurvePoint`\n";
+
+static PyObject * FrsCurve_push_vertex_front( BPy_FrsCurve *self, PyObject *args ) {
 	PyObject *obj;
 
 	if(!( PyArg_ParseTuple(args, "O", &obj) ))
@@ -137,14 +116,83 @@ PyObject * FrsCurve_push_vertex_front( BPy_FrsCurve *self, PyObject *args ) {
 	Py_RETURN_NONE;
 }
 
-PyObject * FrsCurve_empty( BPy_FrsCurve *self ) {
+static char FrsCurve_empty___doc__[] =
+".. method:: empty()\n"
+"\n"
+"   Returns true if the FrsCurve doesn't have any Vertex yet.\n"
+"\n"
+"   :return: True if the FrsCurve has no vertices.\n"
+"   :rtype: bool\n";
+
+static PyObject * FrsCurve_empty( BPy_FrsCurve *self ) {
 	return PyBool_from_bool( self->c->empty() );
 }
 
-PyObject * FrsCurve_nSegments( BPy_FrsCurve *self ) {
+static char FrsCurve_nSegments___doc__[] =
+".. method:: nSegments()\n"
+"\n"
+"   Returns the number of segments in the polyline constituing the\n"
+"   FrsCurve.\n"
+"\n"
+"   :return: The number of segments.\n"
+"   :rtype: int\n";
+
+static PyObject * FrsCurve_nSegments( BPy_FrsCurve *self ) {
 	return PyLong_FromLong( self->c->nSegments() );
 }
 
+/*----------------------FrsCurve instance definitions ----------------------------*/
+static PyMethodDef BPy_FrsCurve_methods[] = {	
+	{"push_vertex_back", ( PyCFunction ) FrsCurve_push_vertex_back, METH_VARARGS, FrsCurve_push_vertex_back___doc__},
+	{"push_vertex_front", ( PyCFunction ) FrsCurve_push_vertex_front, METH_VARARGS, FrsCurve_push_vertex_front___doc__},
+	{"empty", ( PyCFunction ) FrsCurve_empty, METH_NOARGS, FrsCurve_empty___doc__},
+	{"nSegments", ( PyCFunction ) FrsCurve_nSegments, METH_NOARGS, FrsCurve_nSegments___doc__},
+	{NULL, NULL, 0, NULL}
+};
+
+/*-----------------------BPy_FrsCurve type definition ------------------------------*/
+
+PyTypeObject FrsCurve_Type = {
+	PyVarObject_HEAD_INIT(NULL, 0)
+	"FrsCurve",                     /* tp_name */
+	sizeof(BPy_FrsCurve),           /* 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 */
+	FrsCurve___doc__,               /* tp_doc */
+	0,                              /* tp_traverse */
+	0,                              /* tp_clear */
+	0,                              /* tp_richcompare */
+	0,                              /* tp_weaklistoffset */
+	0,                              /* tp_iter */
+	0,                              /* tp_iternext */
+	BPy_FrsCurve_methods,           /* tp_methods */
+	0,                              /* tp_members */
+	0,                              /* tp_getset */
+	&Interface1D_Type,              /* tp_base */
+	0,                              /* tp_dict */
+	0,                              /* tp_descr_get */
+	0,                              /* tp_descr_set */
+	0,                              /* tp_dictoffset */
+	(initproc)FrsCurve___init__,    /* tp_init */
+	0,                              /* tp_alloc */
+	0,                              /* tp_new */
+};
+
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus