Fix T40191: Misleading TypeError message when registering CollectionProperty wtihout kwarg "type".

Turned up to be a cleanup of doc in that whole module...

1 files changed, 118 insertions, 28 deletions

diff --git a/source/blender/python/intern/bpy_props.c b/source/blender/python/intern/bpy_props.c
index 6e36680ec4a..9a8c3d89e8d 100644
--- a/source/blender/python/intern/bpy_props.c
+++ b/source/blender/python/intern/bpy_props.c
@@ -79,8 +79,8 @@ static EnumPropertyItem property_flag_enum_items[] = {
 	{0, NULL, 0, NULL, NULL}};
 
 #define BPY_PROPDEF_OPTIONS_ENUM_DOC \
-"   :type default: string or set\n" \
 "   :arg options: Enumerator in ['HIDDEN', 'SKIP_SAVE', 'ANIMATABLE', 'ENUM_FLAG', 'LIBRARY_EDITABLE'].\n" \
+"   :type options: set\n" \
 
 /* subtypes */
 /* XXX Keep in sync with rna_rna.c's property_subtype_items ???
@@ -1818,23 +1818,62 @@ static void bpy_prop_callback_assign_enum(struct PropertyRNA *prop, PyObject *ge
 "   :arg name: Name used in the user interface.\n" \
 "   :type name: string\n" \
 
-
 #define BPY_PROPDEF_DESC_DOC \
 "   :arg description: Text used for the tooltip and api documentation.\n" \
 "   :type description: string\n" \
 
-
 #define BPY_PROPDEF_UNIT_DOC \
 "   :arg unit: Enumerator in ['NONE', 'LENGTH', 'AREA', 'VOLUME', 'ROTATION', 'TIME', 'VELOCITY', 'ACCELERATION'].\n" \
 "   :type unit: string\n"	\
 
+#define BPY_PROPDEF_NUM_MIN_DOC \
+"   :arg min: Hard minimum, trying to assign a value below will silently assign this minimum instead.\n" \
+
+#define BPY_PROPDEF_NUM_MAX_DOC \
+"   :arg max: Hard maximum, trying to assign a value above will silently assign this maximum instead.\n" \
+
+#define BPY_PROPDEF_NUM_SOFTMIN_DOC \
+"   :arg soft_min: Soft minimum (>= *min*), user won't be able to drag the widget below this value in the UI.\n" \
+
+#define BPY_PROPDEF_NUM_SOFTMAX_DOC \
+"   :arg soft_max: Soft maximum (<= *max*), user won't be able to drag the widget above this value in the UI.\n" \
+
+#define BPY_PROPDEF_VECSIZE_DOC \
+"   :arg size: Vector dimensions in [1, " STRINGIFY(PYRNA_STACK_ARRAY) "].\n" \
+"   :type size: int\n" \
+
+#define BPY_PROPDEF_INT_STEP_DOC \
+"   :arg step: Step of increment/decrement in UI, in [1, 100], defaults to 1 (WARNING: unused currently!).\n" \
+"   :type step: int\n" \
+
+#define BPY_PROPDEF_FLOAT_STEP_DOC \
+"   :arg step: Step of increment/decrement in UI, in [1, 100], defaults to 3 (WARNING: actual value is /100).\n" \
+"   :type step: int\n" \
+
+#define BPY_PROPDEF_FLOAT_PREC_DOC \
+"   :arg precision: Maximum number of decimal digits to display, in [0, 6].\n" \
+"   :type precision: int\n" \
 
 #define BPY_PROPDEF_UPDATE_DOC \
-"   :arg update: function to be called when this value is modified,\n" \
+"   :arg update: Function to be called when this value is modified,\n" \
 "      This function must take 2 values (self, context) and return None.\n" \
 "      *Warning* there are no safety checks to avoid infinite recursion.\n" \
 "   :type update: function\n" \
 
+#define BPY_PROPDEF_GET_DOC \
+"   :arg get: Function to be called when this value is 'read',\n" \
+"      This function must take 1 value (self) and return the value of the property.\n" \
+"   :type get: function\n" \
+
+#define BPY_PROPDEF_SET_DOC \
+"   :arg set: Function to be called when this value is 'written',\n" \
+"      This function must take 2 values (self, value) and return None.\n" \
+"   :type set: function\n" \
+
+#define BPY_PROPDEF_TYPE_DOC \
+"   :arg type: A subclass of :class:`bpy.types.PropertyGroup`.\n" \
+"   :type type: class\n" \
+
 #if 0
 static int bpy_struct_id_used(StructRNA *srna, char *identifier)
 {
@@ -1865,6 +1904,8 @@ BPY_PROPDEF_DESC_DOC
 BPY_PROPDEF_OPTIONS_DOC
 BPY_PROPDEF_SUBTYPE_NUMBER_DOC
 BPY_PROPDEF_UPDATE_DOC
+BPY_PROPDEF_GET_DOC
+BPY_PROPDEF_SET_DOC
 );
 static PyObject *BPy_BoolProperty(PyObject *self, PyObject *args, PyObject *kw)
 {
@@ -1946,9 +1987,10 @@ BPY_PROPDEF_DESC_DOC
 "   :type default: sequence\n"
 BPY_PROPDEF_OPTIONS_DOC
 BPY_PROPDEF_SUBTYPE_ARRAY_DOC
-"   :arg size: Vector dimensions in [1, and " STRINGIFY(PYRNA_STACK_ARRAY) "].\n"
-"   :type size: int\n"
+BPY_PROPDEF_VECSIZE_DOC
 BPY_PROPDEF_UPDATE_DOC
+BPY_PROPDEF_GET_DOC
+BPY_PROPDEF_SET_DOC
 );
 static PyObject *BPy_BoolVectorProperty(PyObject *self, PyObject *args, PyObject *kw)
 {
@@ -2042,9 +2084,20 @@ PyDoc_STRVAR(BPy_IntProperty_doc,
 "\n"
 BPY_PROPDEF_NAME_DOC
 BPY_PROPDEF_DESC_DOC
+BPY_PROPDEF_NUM_MIN_DOC
+"   :type min: int\n"
+BPY_PROPDEF_NUM_MAX_DOC
+"   :type max: int\n"
+BPY_PROPDEF_NUM_SOFTMAX_DOC
+"   :type soft_min: int\n"
+BPY_PROPDEF_NUM_SOFTMIN_DOC
+"   :type soft_max: int\n"
+BPY_PROPDEF_INT_STEP_DOC
 BPY_PROPDEF_OPTIONS_DOC
 BPY_PROPDEF_SUBTYPE_NUMBER_DOC
 BPY_PROPDEF_UPDATE_DOC
+BPY_PROPDEF_GET_DOC
+BPY_PROPDEF_SET_DOC
 );
 static PyObject *BPy_IntProperty(PyObject *self, PyObject *args, PyObject *kw)
 {
@@ -2116,6 +2169,7 @@ PyDoc_STRVAR(BPy_IntVectorProperty_doc,
                                 "default=(0, 0, 0), min=-2**31, max=2**31-1, "
                                 "soft_min=-2**31, "
                                 "soft_max=2**31-1, "
+                                "step=1, "
                                 "options={'ANIMATABLE'}, "
                                 "subtype='NONE', "
                                 "size=3, "
@@ -2129,11 +2183,21 @@ BPY_PROPDEF_NAME_DOC
 BPY_PROPDEF_DESC_DOC
 "   :arg default: sequence of ints the length of *size*.\n"
 "   :type default: sequence\n"
+BPY_PROPDEF_NUM_MIN_DOC
+"   :type min: int\n"
+BPY_PROPDEF_NUM_MAX_DOC
+"   :type max: int\n"
+BPY_PROPDEF_NUM_SOFTMIN_DOC
+"   :type soft_min: int\n"
+BPY_PROPDEF_NUM_SOFTMAX_DOC
+"   :type soft_max: int\n"
+BPY_PROPDEF_INT_STEP_DOC
 BPY_PROPDEF_OPTIONS_DOC
 BPY_PROPDEF_SUBTYPE_ARRAY_DOC
-"   :arg size: Vector dimensions in [1, and " STRINGIFY(PYRNA_STACK_ARRAY) "].\n"
-"   :type size: int\n"
+BPY_PROPDEF_VECSIZE_DOC
 BPY_PROPDEF_UPDATE_DOC
+BPY_PROPDEF_GET_DOC
+BPY_PROPDEF_SET_DOC
 );
 static PyObject *BPy_IntVectorProperty(PyObject *self, PyObject *args, PyObject *kw)
 {
@@ -2234,12 +2298,22 @@ PyDoc_STRVAR(BPy_FloatProperty_doc,
 "\n"
 BPY_PROPDEF_NAME_DOC
 BPY_PROPDEF_DESC_DOC
+BPY_PROPDEF_NUM_MIN_DOC
+"   :type min: float\n"
+BPY_PROPDEF_NUM_MAX_DOC
+"   :type max: float\n"
+BPY_PROPDEF_NUM_SOFTMIN_DOC
+"   :type soft_min: float\n"
+BPY_PROPDEF_NUM_SOFTMAX_DOC
+"   :type soft_max: float\n"
+BPY_PROPDEF_FLOAT_STEP_DOC
+BPY_PROPDEF_FLOAT_PREC_DOC
 BPY_PROPDEF_OPTIONS_DOC
 BPY_PROPDEF_SUBTYPE_NUMBER_DOC
 BPY_PROPDEF_UNIT_DOC
 BPY_PROPDEF_UPDATE_DOC
-"   :arg precision: Number of digits of precision to display.\n"
-"   :type precision: int\n"
+BPY_PROPDEF_GET_DOC
+BPY_PROPDEF_SET_DOC
 );
 static PyObject *BPy_FloatProperty(PyObject *self, PyObject *args, PyObject *kw)
 {
@@ -2325,6 +2399,7 @@ PyDoc_STRVAR(BPy_FloatVectorProperty_doc,
                                   "precision=2, "
                                   "options={'ANIMATABLE'}, "
                                   "subtype='NONE', "
+                                  "unit='NONE', "
                                   "size=3, "
                                   "update=None, "
                                   "get=None, "
@@ -2336,14 +2411,23 @@ BPY_PROPDEF_NAME_DOC
 BPY_PROPDEF_DESC_DOC
 "   :arg default: sequence of floats the length of *size*.\n"
 "   :type default: sequence\n"
+BPY_PROPDEF_NUM_MIN_DOC
+"   :type min: float\n"
+BPY_PROPDEF_NUM_MAX_DOC
+"   :type max: float\n"
+BPY_PROPDEF_NUM_SOFTMIN_DOC
+"   :type soft_min: float\n"
+BPY_PROPDEF_NUM_SOFTMAX_DOC
+"   :type soft_max: float\n"
 BPY_PROPDEF_OPTIONS_DOC
+BPY_PROPDEF_FLOAT_STEP_DOC
+BPY_PROPDEF_FLOAT_PREC_DOC
 BPY_PROPDEF_SUBTYPE_ARRAY_DOC
 BPY_PROPDEF_UNIT_DOC
-"   :arg size: Vector dimensions in [1, and " STRINGIFY(PYRNA_STACK_ARRAY) "].\n"
-"   :type size: int\n"
-"   :arg precision: Number of digits of precision to display.\n"
-"   :type precision: int\n"
+BPY_PROPDEF_VECSIZE_DOC
 BPY_PROPDEF_UPDATE_DOC
+BPY_PROPDEF_GET_DOC
+BPY_PROPDEF_SET_DOC
 );
 static PyObject *BPy_FloatVectorProperty(PyObject *self, PyObject *args, PyObject *kw)
 {
@@ -2449,9 +2533,13 @@ BPY_PROPDEF_NAME_DOC
 BPY_PROPDEF_DESC_DOC
 "   :arg default: initializer string.\n"
 "   :type default: string\n"
+"   :arg maxlen: maximum length of the string.\n"
+"   :type maxlen: int\n"
 BPY_PROPDEF_OPTIONS_DOC
 BPY_PROPDEF_SUBTYPE_STRING_DOC
 BPY_PROPDEF_UPDATE_DOC
+BPY_PROPDEF_GET_DOC
+BPY_PROPDEF_SET_DOC
 );
 static PyObject *BPy_StringProperty(PyObject *self, PyObject *args, PyObject *kw)
 {
@@ -2526,12 +2614,6 @@ PyDoc_STRVAR(BPy_EnumProperty_doc,
 "\n"
 "   Returns a new enumerator property definition.\n"
 "\n"
-BPY_PROPDEF_NAME_DOC
-BPY_PROPDEF_DESC_DOC
-"   :arg default: The default value for this enum, a string from the identifiers used in *items*.\n"
-"      If the *ENUM_FLAG* option is used this must be a set of such string identifiers instead.\n"
-BPY_PROPDEF_OPTIONS_ENUM_DOC
-"   :type options: set\n"
 "   :arg items: sequence of enum items formatted:\n"
 "      [(identifier, name, description, icon, number), ...] where the identifier is used\n"
 "      for python access and other values are used for the interface.\n"
@@ -2545,7 +2627,15 @@ BPY_PROPDEF_OPTIONS_ENUM_DOC
 "      WARNING: There is a known bug with using a callback,\n"
 "      Python must keep a reference to the strings returned or Blender will crash.\n"
 "   :type items: sequence of string tuples or a function\n"
+BPY_PROPDEF_NAME_DOC
+BPY_PROPDEF_DESC_DOC
+"   :arg default: The default value for this enum, a string from the identifiers used in *items*.\n"
+"      If the *ENUM_FLAG* option is used this must be a set of such string identifiers instead.\n"
+"   :type default: string or set\n"
+BPY_PROPDEF_OPTIONS_ENUM_DOC
 BPY_PROPDEF_UPDATE_DOC
+BPY_PROPDEF_GET_DOC
+BPY_PROPDEF_SET_DOC
 );
 static PyObject *BPy_EnumProperty(PyObject *self, PyObject *args, PyObject *kw)
 {
@@ -2685,15 +2775,15 @@ static StructRNA *pointer_type_from_py(PyObject *value, const char *error_prefix
 }
 
 PyDoc_STRVAR(BPy_PointerProperty_doc,
-".. function:: PointerProperty(type=\"\", "
+".. function:: PointerProperty(type=None, "
+                              "name=\"\", "
                               "description=\"\", "
                               "options={'ANIMATABLE'}, "
                               "update=None)\n"
 "\n"
 "   Returns a new pointer property definition.\n"
 "\n"
-"   :arg type: A subclass of :class:`bpy.types.PropertyGroup`.\n"
-"   :type type: class\n"
+BPY_PROPDEF_TYPE_DOC
 BPY_PROPDEF_NAME_DOC
 BPY_PROPDEF_DESC_DOC
 BPY_PROPDEF_OPTIONS_DOC
@@ -2750,15 +2840,14 @@ static PyObject *BPy_PointerProperty(PyObject *self, PyObject *args, PyObject *k
 }
 
 PyDoc_STRVAR(BPy_CollectionProperty_doc,
-".. function:: CollectionProperty(items, "
-                                 "type=\"\", "
+".. function:: CollectionProperty(type=None, "
+                                 "name=\"\", "
                                  "description=\"\", "
                                  "options={'ANIMATABLE'})\n"
 "\n"
 "   Returns a new collection property definition.\n"
 "\n"
-"   :arg type: A subclass of :class:`bpy.types.PropertyGroup`.\n"
-"   :type type: class\n"
+BPY_PROPDEF_TYPE_DOC
 BPY_PROPDEF_NAME_DOC
 BPY_PROPDEF_DESC_DOC
 BPY_PROPDEF_OPTIONS_DOC
@@ -2884,7 +2973,8 @@ static struct PyModuleDef props_module = {
 	PyModuleDef_HEAD_INIT,
 	"bpy.props",
 	"This module defines properties to extend blenders internal data, the result of these functions"
-	" is used to assign properties to classes registered with blender and can't be used directly.",
+	" is used to assign properties to classes registered with blender and can't be used directly.\n"
+	".. warning:: All parameters to these functions must be passed as keywords.",
 	-1, /* multiple "initialization" just copies the module dict. */
 	props_methods,
 	NULL, NULL, NULL, NULL