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, 91 insertions, 57 deletions

diff --git a/source/blender/freestyle/intern/python/Interface1D/Curve/BPy_Chain.cpp b/source/blender/freestyle/intern/python/Interface1D/Curve/BPy_Chain.cpp
index e3b6927dbbc..7958a35b851 100644
--- a/source/blender/freestyle/intern/python/Interface1D/Curve/BPy_Chain.cpp
+++ b/source/blender/freestyle/intern/python/Interface1D/Curve/BPy_Chain.cpp
@@ -10,64 +10,31 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for Chain instance  -----------*/
-static int Chain___init__(BPy_Chain *self, PyObject *args, PyObject *kwds);
-static PyObject * Chain_push_viewedge_back( BPy_Chain *self, PyObject *args );
-static PyObject * Chain_push_viewedge_front( BPy_Chain *self, PyObject *args );
-
-
-/*----------------------Chain instance definitions ----------------------------*/
-static PyMethodDef BPy_Chain_methods[] = {	
-	{"push_viewedge_back", ( PyCFunction ) Chain_push_viewedge_back, METH_VARARGS, "(ViewEdge ve, bool orientation) Adds a ViewEdge at the end of the chain."},
-	{"push_viewedge_front", ( PyCFunction ) Chain_push_viewedge_front, METH_VARARGS, "(ViewEdge ve, bool orientation) Adds a ViewEdge at the beginning of the chain."},
-	{NULL, NULL, 0, NULL}
-};
-
-/*-----------------------BPy_Chain type definition ------------------------------*/
-
-PyTypeObject Chain_Type = {
-	PyVarObject_HEAD_INIT(NULL, 0)
-	"Chain",                        /* tp_name */
-	sizeof(BPy_Chain),              /* 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 */
-	"Chain objects",                /* tp_doc */
-	0,                              /* tp_traverse */
-	0,                              /* tp_clear */
-	0,                              /* tp_richcompare */
-	0,                              /* tp_weaklistoffset */
-	0,                              /* tp_iter */
-	0,                              /* tp_iternext */
-	BPy_Chain_methods,              /* tp_methods */
-	0,                              /* tp_members */
-	0,                              /* tp_getset */
-	&FrsCurve_Type,                 /* tp_base */
-	0,                              /* tp_dict */
-	0,                              /* tp_descr_get */
-	0,                              /* tp_descr_set */
-	0,                              /* tp_dictoffset */
-	(initproc)Chain___init__,       /* tp_init */
-	0,                              /* tp_alloc */
-	0,                              /* tp_new */
-};
-
 //------------------------INSTANCE METHODS ----------------------------------
 
+static char Chain___doc__[] =
+"Class to represent a 1D elements issued from the chaining process.  A\n"
+"Chain is the last step before the :class:`Stroke` and is used in the\n"
+"Splitting and Creation processes.\n"
+"\n"
+".. method:: __init__()\n"
+"\n"
+"   Defult constructor.\n"
+"\n"
+".. method:: __init__(iBrother)\n"
+"\n"
+"   Copy constructor.\n"
+"\n"
+"   :arg iBrother: A Chain object.\n"
+"   :type iBrother: :class:`Chain`\n"
+"\n"
+".. method:: __init__(id)\n"
+"\n"
+"   Builds a chain from its Id.\n"
+"\n"
+"   :arg id: An Id object.\n"
+"   :type id: :class:`Id`\n";
+
 int Chain___init__(BPy_Chain *self, PyObject *args, PyObject *kwds)
 {
 
@@ -97,6 +64,16 @@ int Chain___init__(BPy_Chain *self, PyObject *args, PyObject *kwds)
 	return 0;
 }
 
+static char Chain_push_viewedge_back___doc__[] =
+".. method:: push_viewedge_back(iViewEdge, orientation)\n"
+"\n"
+"   Adds a ViewEdge at the end of the Chain.\n"
+"\n"
+"   :arg iViewEdge: The ViewEdge that must be added.\n"
+"   :type iViewEdge: :class:`ViewEdge`\n"
+"   :arg orientation: The orientation with which the ViewEdge must be\n"
+"      processed.\n"
+"   :type orientation: bool\n";
 
 PyObject * Chain_push_viewedge_back( BPy_Chain *self, PyObject *args ) {
 	PyObject *obj1 = 0, *obj2 = 0;
@@ -111,6 +88,17 @@ PyObject * Chain_push_viewedge_back( BPy_Chain *self, PyObject *args ) {
 	Py_RETURN_NONE;
 }
 
+static char Chain_push_viewedge_front___doc__[] =
+".. method:: push_viewedge_front(iViewEdge, orientation)\n"
+"\n"
+"   Adds a ViewEdge at the beginning of the Chain.\n"
+"\n"
+"   :arg iViewEdge: The ViewEdge that must be added.\n"
+"   :type iViewEdge: :class:`ViewEdge`\n"
+"   :arg orientation: The orientation with which the ViewEdge must be\n"
+"      processed.\n"
+"   :type orientation: bool\n";
+
 PyObject * Chain_push_viewedge_front( BPy_Chain *self, PyObject *args ) {
 	PyObject *obj1 = 0, *obj2 = 0;
 
@@ -124,9 +112,55 @@ PyObject * Chain_push_viewedge_front( BPy_Chain *self, PyObject *args ) {
 	Py_RETURN_NONE;
 }
 
+/*----------------------Chain instance definitions ----------------------------*/
+static PyMethodDef BPy_Chain_methods[] = {	
+	{"push_viewedge_back", ( PyCFunction ) Chain_push_viewedge_back, METH_VARARGS, Chain_push_viewedge_back___doc__},
+	{"push_viewedge_front", ( PyCFunction ) Chain_push_viewedge_front, METH_VARARGS, Chain_push_viewedge_front___doc__},
+	{NULL, NULL, 0, NULL}
+};
 
+/*-----------------------BPy_Chain type definition ------------------------------*/
 
-
+PyTypeObject Chain_Type = {
+	PyVarObject_HEAD_INIT(NULL, 0)
+	"Chain",                        /* tp_name */
+	sizeof(BPy_Chain),              /* 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 */
+	Chain___doc__,                  /* tp_doc */
+	0,                              /* tp_traverse */
+	0,                              /* tp_clear */
+	0,                              /* tp_richcompare */
+	0,                              /* tp_weaklistoffset */
+	0,                              /* tp_iter */
+	0,                              /* tp_iternext */
+	BPy_Chain_methods,              /* tp_methods */
+	0,                              /* tp_members */
+	0,                              /* tp_getset */
+	&FrsCurve_Type,                 /* tp_base */
+	0,                              /* tp_dict */
+	0,                              /* tp_descr_get */
+	0,                              /* tp_descr_set */
+	0,                              /* tp_dictoffset */
+	(initproc)Chain___init__,       /* tp_init */
+	0,                              /* tp_alloc */
+	0,                              /* tp_new */
+};
 
 ///////////////////////////////////////////////////////////////////////////////////////////