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, 147 insertions, 76 deletions

diff --git a/source/blender/freestyle/intern/python/BPy_FrsNoise.cpp b/source/blender/freestyle/intern/python/BPy_FrsNoise.cpp
index 8c21fa63ba1..ed6be31bd47 100644
--- a/source/blender/freestyle/intern/python/BPy_FrsNoise.cpp
+++ b/source/blender/freestyle/intern/python/BPy_FrsNoise.cpp
@@ -9,72 +9,6 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for FrsNoise instance  -----------*/
-static int FrsNoise___init__(BPy_FrsNoise *self, PyObject *args, PyObject *kwds);
-static void FrsNoise___dealloc__(BPy_FrsNoise *self);
-static PyObject * FrsNoise___repr__(BPy_FrsNoise *self);
-
-static PyObject * FrsNoise_turbulence1( BPy_FrsNoise *self, PyObject *args);
-static PyObject * FrsNoise_turbulence2( BPy_FrsNoise *self, PyObject *args);
-static PyObject * FrsNoise_turbulence3( BPy_FrsNoise *self, PyObject *args);
-static PyObject * FrsNoise_smoothNoise1( BPy_FrsNoise *self, PyObject *args);
-static PyObject * FrsNoise_smoothNoise2( BPy_FrsNoise *self, PyObject *args);
-static PyObject * FrsNoise_smoothNoise3( BPy_FrsNoise *self, PyObject *args);
-
-/*----------------------FrsNoise instance definitions ----------------------------*/
-static PyMethodDef BPy_FrsNoise_methods[] = {
-	{"turbulence1", ( PyCFunction ) FrsNoise_turbulence1, METH_VARARGS, "(float arg, float freq, float amp, unsigned oct=4) Returns a noise value for a 1D element"},
-	{"turbulence2", ( PyCFunction ) FrsNoise_turbulence2, METH_VARARGS, "([x, y], float freq, float amp, unsigned oct=4) Returns a noise value for a 2D element"},
-	{"turbulence3", ( PyCFunction ) FrsNoise_turbulence3, METH_VARARGS, "([x, y, z], float freq, float amp, unsigned oct=4) Returns a noise value for a 3D element"},
-	{"smoothNoise1", ( PyCFunction ) FrsNoise_smoothNoise1, METH_VARARGS, "(float arg) Returns a smooth noise value for a 1D element "},
-	{"smoothNoise2", ( PyCFunction ) FrsNoise_smoothNoise2, METH_VARARGS, "([x, y]) Returns a smooth noise value for a 2D element "},
-	{"smoothNoise3", ( PyCFunction ) FrsNoise_smoothNoise3, METH_VARARGS, "([x, y, z]) Returns a smooth noise value for a 3D element "},
-	{NULL, NULL, 0, NULL}
-};
-
-/*-----------------------BPy_FrsNoise type definition ------------------------------*/
-
-PyTypeObject FrsNoise_Type = {
-	PyVarObject_HEAD_INIT(NULL, 0)
-	"FrsNoise",                     /* tp_name */
-	sizeof(BPy_FrsNoise),           /* tp_basicsize */
-	0,                              /* tp_itemsize */
-	(destructor)FrsNoise___dealloc__, /* tp_dealloc */
-	0,                              /* tp_print */
-	0,                              /* tp_getattr */
-	0,                              /* tp_setattr */
-	0,                              /* tp_reserved */
-	(reprfunc)FrsNoise___repr__,    /* 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 */
-	"FrsNoise objects",             /* tp_doc */
-	0,                              /* tp_traverse */
-	0,                              /* tp_clear */
-	0,                              /* tp_richcompare */
-	0,                              /* tp_weaklistoffset */
-	0,                              /* tp_iter */
-	0,                              /* tp_iternext */
-	BPy_FrsNoise_methods,           /* tp_methods */
-	0,                              /* tp_members */
-	0,                              /* tp_getset */
-	0,                              /* tp_base */
-	0,                              /* tp_dict */
-	0,                              /* tp_descr_get */
-	0,                              /* tp_descr_set */
-	0,                              /* tp_dictoffset */
-	(initproc)FrsNoise___init__,    /* tp_init */
-	0,                              /* tp_alloc */
-	PyType_GenericNew,              /* tp_new */
-};
-
 //-------------------MODULE INITIALIZATION--------------------------------
 int FrsNoise_Init( PyObject *module )
 {
@@ -91,7 +25,14 @@ int FrsNoise_Init( PyObject *module )
 
 //------------------------INSTANCE METHODS ----------------------------------
 
-int FrsNoise___init__(BPy_FrsNoise *self, PyObject *args, PyObject *kwds)
+static char FrsNoise___doc__[] =
+"Class to provide Perlin noise functionalities.\n"
+"\n"
+".. method:: __init__()\n"
+"\n"
+"   Builds a Noise object.\n";
+
+static int FrsNoise___init__(BPy_FrsNoise *self, PyObject *args, PyObject *kwds)
 {
 	if(!( PyArg_ParseTuple(args, "") ))
 		return -1;
@@ -99,20 +40,35 @@ int FrsNoise___init__(BPy_FrsNoise *self, PyObject *args, PyObject *kwds)
 	return 0;
 }
 
-void FrsNoise___dealloc__(BPy_FrsNoise* self)
+static void FrsNoise___dealloc__(BPy_FrsNoise* self)
 {
 	delete self->n;
     Py_TYPE(self)->tp_free((PyObject*)self);
 }
 
 
-PyObject * FrsNoise___repr__(BPy_FrsNoise* self)
+static PyObject * FrsNoise___repr__(BPy_FrsNoise* self)
 {
     return PyUnicode_FromFormat("FrsNoise - address: %p", self->n );
 }
 
-
-PyObject * FrsNoise_turbulence1( BPy_FrsNoise *self , PyObject *args) {
+static char FrsNoise_turbulence1___doc__[] =
+".. method:: turbulence1(v, freq, amp, oct=4)\n"
+"\n"
+"   Returns a noise value for a 1D element.\n"
+"\n"
+"   :arg v: One-dimensional sample point.\n"
+"   :type v: float\n"
+"   :arg freq: Noise frequency.\n"
+"   :type freq: float\n"
+"   :arg amp: Amplitude.\n"
+"   :type amp: float\n"
+"   :arg oct: Number of octaves.\n"
+"   :type oct: int\n"
+"   :return: A noise value.\n"
+"   :rtype: float\n";
+
+static PyObject * FrsNoise_turbulence1( BPy_FrsNoise *self , PyObject *args) {
 	float f1, f2, f3;
 	unsigned int i = 4;
 
@@ -122,7 +78,23 @@ PyObject * FrsNoise_turbulence1( BPy_FrsNoise *self , PyObject *args) {
 	return PyFloat_FromDouble( self->n->turbulence1(f1, f2, f3, i) );
 }
 
-PyObject * FrsNoise_turbulence2( BPy_FrsNoise *self , PyObject *args) {
+static char FrsNoise_turbulence2___doc__[] =
+".. method:: turbulence2(v, freq, amp, oct=4)\n"
+"\n"
+"   Returns a noise value for a 2D element.\n"
+"\n"
+"   :arg v: Two-dimensional sample point.\n"
+"   :type v: :class:`Mathutils.Vector`, list or tuple of 2 real numbers\n"
+"   :arg freq: Noise frequency.\n"
+"   :type freq: float\n"
+"   :arg amp: Amplitude.\n"
+"   :type amp: float\n"
+"   :arg oct: Number of octaves.\n"
+"   :type oct: int\n"
+"   :return: A noise value.\n"
+"   :rtype: float\n";
+
+static PyObject * FrsNoise_turbulence2( BPy_FrsNoise *self , PyObject *args) {
 	PyObject *obj1;
 	float f2, f3;
 	unsigned int i = 4;
@@ -139,7 +111,23 @@ PyObject * FrsNoise_turbulence2( BPy_FrsNoise *self , PyObject *args) {
 	return PyFloat_FromDouble( t );
 }
 
-PyObject * FrsNoise_turbulence3( BPy_FrsNoise *self , PyObject *args) {
+static char FrsNoise_turbulence3___doc__[] =
+".. method:: turbulence3(v, freq, amp, oct=4)\n"
+"\n"
+"   Returns a noise value for a 3D element.\n"
+"\n"
+"   :arg v: Three-dimensional sample point.\n"
+"   :type v: :class:`Mathutils.Vector`, list or tuple of 3 real numbers\n"
+"   :arg freq: Noise frequency.\n"
+"   :type freq: float\n"
+"   :arg amp: Amplitude.\n"
+"   :type amp: float\n"
+"   :arg oct: Number of octaves.\n"
+"   :type oct: int\n"
+"   :return: A noise value.\n"
+"   :rtype: float\n";
+
+static PyObject * FrsNoise_turbulence3( BPy_FrsNoise *self , PyObject *args) {
 	PyObject *obj1;
 	float f2, f3;
 	unsigned int i = 4;
@@ -156,7 +144,17 @@ PyObject * FrsNoise_turbulence3( BPy_FrsNoise *self , PyObject *args) {
 	return PyFloat_FromDouble( t );
 }
 
-PyObject * FrsNoise_smoothNoise1( BPy_FrsNoise *self , PyObject *args) {
+static char FrsNoise_smoothNoise1___doc__[] =
+".. method:: smoothNoise1(v)\n"
+"\n"
+"   Returns a smooth noise value for a 1D element.\n"
+"\n"
+"   :arg v: One-dimensional sample point.\n"
+"   :type v: float\n"
+"   :return: A smooth noise value.\n"
+"   :rtype: float\n";
+
+static PyObject * FrsNoise_smoothNoise1( BPy_FrsNoise *self , PyObject *args) {
 	float f;
 
 	if(!( PyArg_ParseTuple(args, "f", &f) ))
@@ -165,7 +163,17 @@ PyObject * FrsNoise_smoothNoise1( BPy_FrsNoise *self , PyObject *args) {
 	return PyFloat_FromDouble( self->n->smoothNoise1(f) );
 }
 
-PyObject * FrsNoise_smoothNoise2( BPy_FrsNoise *self , PyObject *args) {
+static char FrsNoise_smoothNoise2___doc__[] =
+".. method:: smoothNoise2(v)\n"
+"\n"
+"   Returns a smooth noise value for a 2D element.\n"
+"\n"
+"   :arg v: Two-dimensional sample point.\n"
+"   :type v: :class:`Mathutils.Vector`, list or tuple of 2 real numbers\n"
+"   :return: A smooth noise value.\n"
+"   :rtype: float\n";
+
+static PyObject * FrsNoise_smoothNoise2( BPy_FrsNoise *self , PyObject *args) {
 	PyObject *obj;
 
 	if(!( PyArg_ParseTuple(args, "O", &obj) ))
@@ -180,7 +188,17 @@ PyObject * FrsNoise_smoothNoise2( BPy_FrsNoise *self , PyObject *args) {
 	return PyFloat_FromDouble( t );
 }
 
-PyObject * FrsNoise_smoothNoise3( BPy_FrsNoise *self , PyObject *args) {
+static char FrsNoise_smoothNoise3___doc__[] =
+".. method:: smoothNoise3(v)\n"
+"\n"
+"   Returns a smooth noise value for a 3D element.\n"
+"\n"
+"   :arg v: Three-dimensional sample point.\n"
+"   :type v: :class:`Mathutils.Vector`, list or tuple of 3 real numbers\n"
+"   :return: A smooth noise value.\n"
+"   :rtype: float\n";
+
+static PyObject * FrsNoise_smoothNoise3( BPy_FrsNoise *self , PyObject *args) {
 	PyObject *obj;
 
 	if(!( PyArg_ParseTuple(args, "O", &obj) ))
@@ -195,6 +213,59 @@ PyObject * FrsNoise_smoothNoise3( BPy_FrsNoise *self , PyObject *args) {
 	return PyFloat_FromDouble( t );
 }
 
+/*----------------------FrsNoise instance definitions ----------------------------*/
+static PyMethodDef BPy_FrsNoise_methods[] = {
+	{"turbulence1", ( PyCFunction ) FrsNoise_turbulence1, METH_VARARGS, FrsNoise_turbulence1___doc__},
+	{"turbulence2", ( PyCFunction ) FrsNoise_turbulence2, METH_VARARGS, FrsNoise_turbulence2___doc__},
+	{"turbulence3", ( PyCFunction ) FrsNoise_turbulence3, METH_VARARGS, FrsNoise_turbulence3___doc__},
+	{"smoothNoise1", ( PyCFunction ) FrsNoise_smoothNoise1, METH_VARARGS, FrsNoise_smoothNoise1___doc__},
+	{"smoothNoise2", ( PyCFunction ) FrsNoise_smoothNoise2, METH_VARARGS, FrsNoise_smoothNoise2___doc__},
+	{"smoothNoise3", ( PyCFunction ) FrsNoise_smoothNoise3, METH_VARARGS, FrsNoise_smoothNoise3___doc__},
+	{NULL, NULL, 0, NULL}
+};
+
+/*-----------------------BPy_FrsNoise type definition ------------------------------*/
+
+PyTypeObject FrsNoise_Type = {
+	PyVarObject_HEAD_INIT(NULL, 0)
+	"FrsNoise",                     /* tp_name */
+	sizeof(BPy_FrsNoise),           /* tp_basicsize */
+	0,                              /* tp_itemsize */
+	(destructor)FrsNoise___dealloc__, /* tp_dealloc */
+	0,                              /* tp_print */
+	0,                              /* tp_getattr */
+	0,                              /* tp_setattr */
+	0,                              /* tp_reserved */
+	(reprfunc)FrsNoise___repr__,    /* 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 */
+	FrsNoise___doc__,               /* tp_doc */
+	0,                              /* tp_traverse */
+	0,                              /* tp_clear */
+	0,                              /* tp_richcompare */
+	0,                              /* tp_weaklistoffset */
+	0,                              /* tp_iter */
+	0,                              /* tp_iternext */
+	BPy_FrsNoise_methods,           /* tp_methods */
+	0,                              /* tp_members */
+	0,                              /* tp_getset */
+	0,                              /* tp_base */
+	0,                              /* tp_dict */
+	0,                              /* tp_descr_get */
+	0,                              /* tp_descr_set */
+	0,                              /* tp_dictoffset */
+	(initproc)FrsNoise___init__,    /* tp_init */
+	0,                              /* tp_alloc */
+	PyType_GenericNew,              /* tp_new */
+};
 
 ///////////////////////////////////////////////////////////////////////////////////////////