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, 36 insertions, 14 deletions

diff --git a/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_Material/BPy_MaterialF0D.cpp b/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_Material/BPy_MaterialF0D.cpp
index 204fa9837f7..1f709947d0e 100644
--- a/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_Material/BPy_MaterialF0D.cpp
+++ b/source/blender/freestyle/intern/python/UnaryFunction0D/UnaryFunction0D_Material/BPy_MaterialF0D.cpp
@@ -8,8 +8,41 @@ extern "C" {
 
 ///////////////////////////////////////////////////////////////////////////////////////////
 
-/*---------------  Python API function prototypes for MaterialF0D instance  -----------*/
-static int MaterialF0D___init__(BPy_MaterialF0D* self, PyObject *args);
+//------------------------INSTANCE METHODS ----------------------------------
+
+static char MaterialF0D___doc__[] =
+".. method:: __init__()\n"
+"\n"
+"   Builds a MaterialF0D object.\n"
+"\n"
+".. method:: __call__(it)\n"
+"\n"
+"   Returns the material of the object evaluated at the\n"
+"   :class:`Interface0D` pointed by the Interface0DIterator.  This\n"
+"   evaluation can be ambiguous (in the case of a :class:`TVertex` for\n"
+"   example.  This functor tries to remove this ambiguity using the\n"
+"   context offered by the 1D element to which the Interface0DIterator\n"
+"   belongs to and by arbitrary chosing the material of the face that\n"
+"   lies on its left when following the 1D element if there are two\n"
+"   different materials on each side of the point.  However, there\n"
+"   still can be problematic cases, and the user willing to deal with\n"
+"   this cases in a specific way should implement its own getMaterial\n"
+"   functor.\n"
+"\n"
+"   :arg it: An Interface0DIterator object.\n"
+"   :type it: :class:`Interface0DIterator`\n"
+"   :return: The material of the object evaluated at the pointed\n"
+"      Interface0D.\n"
+"   :rtype: :class:`Material`\n";
+
+static int MaterialF0D___init__( BPy_MaterialF0D* self, PyObject *args )
+{
+	if( !PyArg_ParseTuple(args, "") )
+		return -1;
+	self->py_uf0D_material.uf0D_material = new Functions0D::MaterialF0D();
+	self->py_uf0D_material.uf0D_material->py_uf0D = (PyObject *)self;
+	return 0;
+}
 
 /*-----------------------BPy_MaterialF0D type definition ------------------------------*/
 
@@ -34,7 +67,7 @@ PyTypeObject MaterialF0D_Type = {
 	0,                              /* tp_setattro */
 	0,                              /* tp_as_buffer */
 	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
-	"MaterialF0D objects",          /* tp_doc */
+	MaterialF0D___doc__,            /* tp_doc */
 	0,                              /* tp_traverse */
 	0,                              /* tp_clear */
 	0,                              /* tp_richcompare */
@@ -54,17 +87,6 @@ PyTypeObject MaterialF0D_Type = {
 	0,                              /* tp_new */
 };
 
-//------------------------INSTANCE METHODS ----------------------------------
-
-int MaterialF0D___init__( BPy_MaterialF0D* self, PyObject *args )
-{
-	if( !PyArg_ParseTuple(args, "") )
-		return -1;
-	self->py_uf0D_material.uf0D_material = new Functions0D::MaterialF0D();
-	self->py_uf0D_material.uf0D_material->py_uf0D = (PyObject *)self;
-	return 0;
-}
-
 ///////////////////////////////////////////////////////////////////////////////////////////
 
 #ifdef __cplusplus