[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [39645] trunk/blender/doc/python_api: add warning about misuse of ID.user_clear() since it can crash blender.

[Campbell Barton]

Revision: 39645
          http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=39645
Author:   campbellbarton
Date:     2011-08-23 11:28:18 +0000 (Tue, 23 Aug 2011)
Log Message:
-----------
add warning about misuse of ID.user_clear() since it can crash blender.

Modified Paths:
--------------
    trunk/blender/doc/python_api/sphinx_doc_gen.py

Added Paths:
-----------
    trunk/blender/doc/python_api/examples/bpy.types.ID.user_clear.1.py

Added: trunk/blender/doc/python_api/examples/bpy.types.ID.user_clear.1.py
===================================================================
--- trunk/blender/doc/python_api/examples/bpy.types.ID.user_clear.1.py	                        (rev 0)
+++ trunk/blender/doc/python_api/examples/bpy.types.ID.user_clear.1.py	2011-08-23 11:28:18 UTC (rev 39645)
@@ -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)

Modified: trunk/blender/doc/python_api/sphinx_doc_gen.py
===================================================================
--- trunk/blender/doc/python_api/sphinx_doc_gen.py	2011-08-23 09:05:12 UTC (rev 39644)
+++ trunk/blender/doc/python_api/sphinx_doc_gen.py	2011-08-23 11:28:18 UTC (rev 39645)
@@ -74,10 +74,10 @@
         "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 @@
         "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 @@
                         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