add warning about misuse of ID.user_clear() since it can crash blender.

1 files changed, 19 insertions, 0 deletions

diff --git a/doc/python_api/examples/bpy.types.ID.user_clear.1.py b/doc/python_api/examples/bpy.types.ID.user_clear.1.py
new file mode 100644
index 00000000000..68c35caa7d4
--- /dev/null
+++ b/doc/python_api/examples/bpy.types.ID.user_clear.1.py
@@ -0,0 +1,19 @@
+"""
+User Clear
+++++++++++
+This function is for advanced use only, misuse can crash blender since the user
+count is used to prevent data being removed when it is used.
+"""
+
+# This example shows what _not_ to do, and will crash blender.
+import bpy
+
+# object which is in the scene.
+obj = bpy.data.objects["Cube"]
+
+# without this, removal would raise an error.
+obj.user_clear()
+
+# runs without an exception
+# but will crash on redraw.
+bpy.data.objects.remove(obj)