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

2 files changed, 24 insertions, 3 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)
diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py
index f8561c719bc..a20e799811b 100644
--- a/doc/python_api/sphinx_doc_gen.py
+++ b/doc/python_api/sphinx_doc_gen.py
@@ -74,10 +74,10 @@ else:
         "bpy.props",
         "bpy.utils",
         "bpy.context",
-        "bpy.types",  # supports filtering
+        #"bpy.types",  # supports filtering
         "bpy.ops",  # supports filtering
         "bpy_extras",
-        # "bge",
+        "bge",
         "aud",
         "bgl",
         "blf",
@@ -85,7 +85,7 @@ else:
         "mathutils.geometry",
     )
 
-    FILTER_BPY_TYPES = ("bpy_struct", "Panel", "Menu", "Operator", "RenderEngine")  # allow
+    FILTER_BPY_TYPES = ("bpy_struct", "Panel", "ID")  # allow
     FILTER_BPY_OPS = ("import.scene", )  # allow
 
     # for quick rebuilds
@@ -744,6 +744,8 @@ def pyrna2sphinx(BASEPATH):
                         descr = prop.name
                     fw("         `%s`, %s, %s\n\n" % (prop.identifier, descr, type_descr))
 
+            write_example_ref("      ", fw, "bpy.types." + struct.identifier + "." + func.identifier)
+
             fw("\n")
 
         # python methods