- new docstrings for bpy.type.Struct methods & some corrections.

- struct.path_to_id() --> path_from_id().

2 files changed, 53 insertions, 22 deletions

diff --git a/source/blender/python/doc/sphinx_doc_gen.py b/source/blender/python/doc/sphinx_doc_gen.py
index 667e282da2c..37bc123ee53 100644
--- a/source/blender/python/doc/sphinx_doc_gen.py
+++ b/source/blender/python/doc/sphinx_doc_gen.py
@@ -481,7 +481,7 @@ def rna2sphinx(BASEPATH):
 
         # c/python methods, only for the base class
         if struct.identifier == "Struct":
-            for attribute, descr in bpy.types.Struct.__bases__[0].__dict__.items():
+            for attribute, descr in sorted(bpy.types.Struct.__bases__[0].__dict__.items()):
                 if type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
                     if descr.__doc__:
                         write_indented_lines("   ", fw, descr.__doc__, False)
diff --git a/source/blender/python/intern/bpy_rna.c b/source/blender/python/intern/bpy_rna.c
index 7d2351d013d..e522861b2aa 100644
--- a/source/blender/python/intern/bpy_rna.c
+++ b/source/blender/python/intern/bpy_rna.c
@@ -1663,8 +1663,8 @@ static PyObject *pyrna_struct_values(BPy_PropertyRNA *self)
 }
 
 /* internal use for insert and delete */
-int pyrna_struct_keyframe_parse(PointerRNA *ptr, PyObject *args, char *error_prefix,
-	char **group_name, char **path_full, int *index, float *cfra) /* return values */
+static int pyrna_struct_keyframe_parse(PointerRNA *ptr, PyObject *args, char *error_prefix,
+	char **path_full, int *index, float *cfra, char **group_name) /* return values */
 {
 	char *path;
 	PropertyRNA *prop;
@@ -1723,18 +1723,18 @@ static char pyrna_struct_keyframe_insert_doc[] =
 "   :arg frame: The frame on which the keyframe is inserted, defaulting to the current frame.\n"
 "   :type frame: float\n"
 "	:arg group: The name of the group the F-Curve should be added to if it doesn't exist yet.\n"
-"	:type group: str\n";
+"	:type group: str";
 
 static PyObject *pyrna_struct_keyframe_insert(BPy_StructRNA *self, PyObject *args)
 {
 	PyObject *result;
 	/* args, pyrna_struct_keyframe_parse handles these */
 	char *path_full= NULL;
-	char *group_name= NULL;
 	int index= -1;
 	float cfra= FLT_MAX;
+    char *group_name= NULL;
 
-	if(pyrna_struct_keyframe_parse(&self->ptr, args, "bpy_struct.keyframe_insert():", &group_name, &path_full, &index, &cfra) == -1)
+	if(pyrna_struct_keyframe_parse(&self->ptr, args, "bpy_struct.keyframe_insert():", &path_full, &index, &cfra, &group_name) == -1)
 		return NULL;
 
 	result= PyBool_FromLong(insert_keyframe((ID *)self->ptr.id.data, NULL, group_name, path_full, index, cfra, 0));
@@ -1753,20 +1753,20 @@ static char pyrna_struct_keyframe_delete_doc[] =
 "   :arg index: array index of the property to remove a key. Defaults to -1 removing all indicies or a single channel if the property is not an array.\n"
 "   :type index: int\n"
 "   :arg frame: The frame on which the keyframe is deleted, defaulting to the current frame.\n"
-"   :type frame: float"
+"   :type frame: float\n"
 "	:arg group: The name of the group the F-Curve should be added to if it doesn't exist yet.\n"
-"	:type group: str\n";;
+"	:type group: str";
 
 static PyObject *pyrna_struct_keyframe_delete(BPy_StructRNA *self, PyObject *args)
 {
 	PyObject *result;
 	/* args, pyrna_struct_keyframe_parse handles these */
 	char *path_full= NULL;
-	char *group_name= NULL;
 	int index= -1;
 	float cfra= FLT_MAX;
+    char *group_name= NULL;
 
-	if(pyrna_struct_keyframe_parse(&self->ptr, args, "bpy_struct.keyframe_delete():", &group_name, &path_full, &index, &cfra) == -1)
+	if(pyrna_struct_keyframe_parse(&self->ptr, args, "bpy_struct.keyframe_delete():", &path_full, &index, &cfra, &group_name) == -1)
 		return NULL;
 
 	result= PyBool_FromLong(delete_keyframe((ID *)self->ptr.id.data, NULL, group_name, path_full, index, cfra, 0));
@@ -1775,6 +1775,16 @@ static PyObject *pyrna_struct_keyframe_delete(BPy_StructRNA *self, PyObject *arg
 	return result;
 }
 
+static char pyrna_struct_driver_add_doc[] =
+".. function:: driver_add(path, index=-1)\n"
+"\n"
+"   Returns the newly created driver or a list of drivers in the case of an array\n"
+"\n"
+"   :arg path: path to the property to drive, analogous to the fcurve's data path.\n"
+"   :type path: string\n"
+"   :arg index: array index of the property drive. Defaults to -1 for all indicies or a single channel if the property is not an array.\n"
+"   :type index: int";
+
 static PyObject *pyrna_struct_driver_add(BPy_StructRNA *self, PyObject *args)
 {
 	char *path, *path_full;
@@ -1868,6 +1878,14 @@ static PyObject *pyrna_struct_is_property_hidden(BPy_StructRNA *self, PyObject *
 	return PyBool_FromLong(hidden);
 }
 
+static char pyrna_struct_path_resolve_doc[] =
+".. function:: path_resolve(path)\n"
+"\n"
+"   Returns the property from the path given or None if the property is not found.\n"
+"\n"
+"   :arg path: path to the property.\n"
+"   :type path: string";
+
 static PyObject *pyrna_struct_path_resolve(BPy_StructRNA *self, PyObject *value)
 {
 	char *path= _PyUnicode_AsString(value);
@@ -1875,7 +1893,7 @@ static PyObject *pyrna_struct_path_resolve(BPy_StructRNA *self, PyObject *value)
 	PropertyRNA *r_prop;
 
 	if(path==NULL) {
-		PyErr_SetString( PyExc_TypeError, "bpy_struct.items(): is only valid for collection types" );
+		PyErr_SetString(PyExc_TypeError, "bpy_struct.path_resolve(): accepts only a single string argument");
 		return NULL;
 	}
 
@@ -1885,20 +1903,28 @@ static PyObject *pyrna_struct_path_resolve(BPy_StructRNA *self, PyObject *value)
 	Py_RETURN_NONE;
 }
 
-static PyObject *pyrna_struct_path_to_id(BPy_StructRNA *self, PyObject *args)
+static char pyrna_struct_path_from_id_doc[] =
+".. function:: path_from_id(property=\"\")\n"
+"\n"
+"   Returns the data path from the ID to this object (string).\n"
+"\n"
+"   :arg property: Optional property name which can be used if the path is to a property of this object.\n"
+"   :type property: string";
+
+static PyObject *pyrna_struct_path_from_id(BPy_StructRNA *self, PyObject *args)
 {
 	char *name= NULL;
 	char *path;
 	PropertyRNA *prop;
 	PyObject *ret;
 
-	if (!PyArg_ParseTuple(args, "|s:path_to_id", &name))
+	if (!PyArg_ParseTuple(args, "|s:path_from_id", &name))
 		return NULL;
 
 	if(name) {
 		prop= RNA_struct_find_property(&self->ptr, name);
 		if(prop==NULL) {
-			PyErr_Format(PyExc_TypeError, "%.200s.path_to_id(\"%.200s\") not found", RNA_struct_identifier(self->ptr.type), name);
+			PyErr_Format(PyExc_TypeError, "%.200s.path_from_id(\"%.200s\") not found", RNA_struct_identifier(self->ptr.type), name);
 			return NULL;
 		}
 
@@ -1909,8 +1935,8 @@ static PyObject *pyrna_struct_path_to_id(BPy_StructRNA *self, PyObject *args)
 	}
 
 	if(path==NULL) {
-		if(name)	PyErr_Format(PyExc_TypeError, "%.200s.path_to_id(\"%s\") found but does not support path creation", RNA_struct_identifier(self->ptr.type), name);
-		else		PyErr_Format(PyExc_TypeError, "%.200s.path_to_id() does not support path creation for this type", RNA_struct_identifier(self->ptr.type));
+		if(name)	PyErr_Format(PyExc_TypeError, "%.200s.path_from_id(\"%s\") found but does not support path creation", RNA_struct_identifier(self->ptr.type), name);
+		else		PyErr_Format(PyExc_TypeError, "%.200s.path_from_id() does not support path creation for this type", RNA_struct_identifier(self->ptr.type));
 		return NULL;
 	}
 
@@ -1927,7 +1953,12 @@ static PyObject *pyrna_struct_recast_type(BPy_StructRNA *self, PyObject *args)
 	return pyrna_struct_CreatePyObject(&r_ptr);
 }
 
-static PyObject *pyrna_prop_path_to_id(BPy_PropertyRNA *self)
+static char pyrna_prop_path_from_id_doc[] =
+".. function:: path_from_id()\n"
+"\n"
+"   Returns the data path from the ID to this property (string).";
+
+static PyObject *pyrna_prop_path_from_id(BPy_PropertyRNA *self)
 {
 	char *path;
 	PropertyRNA *prop = self->prop;
@@ -1936,7 +1967,7 @@ static PyObject *pyrna_prop_path_to_id(BPy_PropertyRNA *self)
 	path= RNA_path_from_ID_to_property(&self->ptr, self->prop);
 
 	if(path==NULL) {
-		PyErr_Format(PyExc_TypeError, "%.200s.%.200s.path_to_id() does not support path creation for this type", RNA_struct_identifier(self->ptr.type), RNA_property_identifier(prop));
+		PyErr_Format(PyExc_TypeError, "%.200s.%.200s.path_from_id() does not support path creation for this type", RNA_struct_identifier(self->ptr.type), RNA_property_identifier(prop));
 		return NULL;
 	}
 
@@ -2746,11 +2777,11 @@ static struct PyMethodDef pyrna_struct_methods[] = {
 	/* maybe this become and ID function */
 	{"keyframe_insert", (PyCFunction)pyrna_struct_keyframe_insert, METH_VARARGS, pyrna_struct_keyframe_insert_doc},
 	{"keyframe_delete", (PyCFunction)pyrna_struct_keyframe_delete, METH_VARARGS, pyrna_struct_keyframe_delete_doc},
-	{"driver_add", (PyCFunction)pyrna_struct_driver_add, METH_VARARGS, NULL},
+	{"driver_add", (PyCFunction)pyrna_struct_driver_add, METH_VARARGS, pyrna_struct_driver_add_doc},
 	{"is_property_set", (PyCFunction)pyrna_struct_is_property_set, METH_VARARGS, NULL},
 	{"is_property_hidden", (PyCFunction)pyrna_struct_is_property_hidden, METH_VARARGS, NULL},
-	{"path_resolve", (PyCFunction)pyrna_struct_path_resolve, METH_O, NULL},
-	{"path_to_id", (PyCFunction)pyrna_struct_path_to_id, METH_VARARGS, NULL},
+	{"path_resolve", (PyCFunction)pyrna_struct_path_resolve, METH_O, pyrna_struct_path_resolve_doc},
+	{"path_from_id", (PyCFunction)pyrna_struct_path_from_id, METH_VARARGS, pyrna_struct_path_from_id_doc},
 	{"recast_type", (PyCFunction)pyrna_struct_recast_type, METH_NOARGS, NULL},
 	{"__dir__", (PyCFunction)pyrna_struct_dir, METH_NOARGS, NULL},
 
@@ -2762,7 +2793,7 @@ static struct PyMethodDef pyrna_struct_methods[] = {
 };
 
 static struct PyMethodDef pyrna_prop_methods[] = {
-	{"path_to_id", (PyCFunction)pyrna_prop_path_to_id, METH_NOARGS, NULL},
+	{"path_from_id", (PyCFunction)pyrna_prop_path_from_id, METH_NOARGS, pyrna_prop_path_from_id_doc},
 	{"__dir__", (PyCFunction)pyrna_prop_dir, METH_NOARGS, NULL},
 	{NULL, NULL, 0, NULL}
 };