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, 52 insertions, 25 deletions

diff --git a/source/blender/freestyle/intern/python/StrokeShader/BPy_CalligraphicShader.cpp b/source/blender/freestyle/intern/python/StrokeShader/BPy_CalligraphicShader.cpp
index 75083a35af0..40afe17268e 100644
--- a/source/blender/freestyle/intern/python/StrokeShader/BPy_CalligraphicShader.cpp
+++ b/source/blender/freestyle/intern/python/StrokeShader/BPy_CalligraphicShader.cpp
@@ -9,8 +9,57 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for CalligraphicShader instance  -----------*/
-static int CalligraphicShader___init__( BPy_CalligraphicShader* self, PyObject *args);
+//------------------------INSTANCE METHODS ----------------------------------
+
+static char CalligraphicShader___doc__[] =
+"[Thickness Shader]\n"
+"\n"
+".. method:: __init__(iMinThickness, iMaxThickness, iOrientation, iClamp)\n"
+"\n"
+"   Builds a CalligraphicShader object.\n"
+"\n"
+"   :arg iMinThickness: The minimum thickness in the direction\n"
+"      perpandicular to the main direction.\n"
+"   :type iMinThickness: float\n"
+"   :arg iMaxThickness: The maximum thickness in the main direction.\n"
+"   :type iMaxThickness: float\n"
+"   :arg iOrientation: The 2D vector giving the main direction.\n"
+"   :type iOrientation: :class:`Mathutils.Vector`\n"
+"   :arg iClamp: If true, the strokes are drawn in black when the stroke\n"
+"      direction is between -90 and 90 degrees with respect to the main\n"
+"      direction and drawn in white otherwise.  If false, the strokes\n"
+"      are always drawn in black.\n"
+"   :type iClamp: bool\n"
+"\n"
+".. method:: shade(s)\n"
+"\n"
+"   Assigns thicknesses to the stroke vertices so that the stroke looks\n"
+"   like made with a calligraphic tool, i.e. the stroke will be the\n"
+"   thickest in a main direction, and the thinest in the direction\n"
+"   perpendicular to this one, and an interpolation inbetween.\n"
+"\n"
+"   :arg s: A Stroke object.\n"
+"   :type s: :class:`Stroke`\n";
+
+static int CalligraphicShader___init__( BPy_CalligraphicShader* self, PyObject *args)
+{
+	double d1, d2;
+	PyObject *obj3 = 0, *obj4 = 0;
+	
+
+	if(!( PyArg_ParseTuple(args, "ddOO", &d1, &d2, &obj3, &obj4) ))
+		return -1;
+	Vec2f *v = Vec2f_ptr_from_PyObject(obj3);
+	if( !v ) {
+		PyErr_SetString(PyExc_TypeError, "argument 3 must be a 2D vector (either a list of 2 elements or Vector)");
+		return -1;
+	}
+	self->py_ss.ss = new CalligraphicShader(d1, d2, *v, bool_from_PyBool(obj4) );
+	delete v;
+
+	return 0;
+
+}
 
 /*-----------------------BPy_CalligraphicShader type definition ------------------------------*/
 
@@ -35,7 +84,7 @@ PyTypeObject CalligraphicShader_Type = {
 	0,                              /* tp_setattro */
 	0,                              /* tp_as_buffer */
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"CalligraphicShader objects",    /* tp_doc */
+	CalligraphicShader___doc__,     /* tp_doc */
 	0,                              /* tp_traverse */
 	0,                              /* tp_clear */
 	0,                              /* tp_richcompare */
@@ -55,28 +104,6 @@ PyTypeObject CalligraphicShader_Type = {
 	0,                              /* tp_new */
 };
 
-//------------------------INSTANCE METHODS ----------------------------------
-
-int CalligraphicShader___init__( BPy_CalligraphicShader* self, PyObject *args)
-{
-	double d1, d2;
-	PyObject *obj3 = 0, *obj4 = 0;
-	
-
-	if(!( PyArg_ParseTuple(args, "ddOO", &d1, &d2, &obj3, &obj4) ))
-		return -1;
-	Vec2f *v = Vec2f_ptr_from_PyObject(obj3);
-	if( !v ) {
-		PyErr_SetString(PyExc_TypeError, "argument 3 must be a 2D vector (either a list of 2 elements or Vector)");
-		return -1;
-	}
-	self->py_ss.ss = new CalligraphicShader(d1, d2, *v, bool_from_PyBool(obj4) );
-	delete v;
-
-	return 0;
-
-}
-
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus